{"openapi":"3.1.0","info":{"title":"depot API","version":"0.0.1"},"components":{"schemas":{"PrepareResponse":{"type":"object","properties":{"status":{"type":"string","enum":["exists","upload"]},"blobId":{"type":"string","format":"uuid"},"uploadSessionId":{"type":"string","format":"uuid"},"partUrls":{"type":"array","items":{"type":"string","format":"uri"}},"partSize":{"type":"integer"},"partCount":{"type":"integer"}},"required":["status","blobId"]},"Error":{"type":"object","properties":{"error":{"type":"string","example":"unauthorized"},"detail":{"type":"string"}},"required":["error"]},"PrepareRequest":{"type":"object","properties":{"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"optional client hash claim — enables the zero-byte dedupe path","example":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"},"size":{"type":"integer","minimum":0,"maximum":5497558138880,"example":17825792}},"required":["size"]},"CompleteResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]},"CompleteRequest":{"type":"object","properties":{"parts":{"type":"array","items":{"type":"object","properties":{"partNumber":{"type":"integer","minimum":1},"etag":{"type":"string","minLength":1}},"required":["partNumber","etag"]},"minItems":1,"description":"collected ETags from the presigned part PUTs"}},"required":["parts"]},"Release":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"projectId":{"type":"string","format":"uuid"},"version":{"type":"string"},"status":{"type":"string","enum":["draft","published"]},"netProtocol":{"type":["string","null"]},"notes":{"type":["string","null"]},"meta":{"type":["object","null"],"additionalProperties":{}},"publishedAt":{"type":["string","null"]}},"required":["id","projectId","version","status","netProtocol","notes","meta","publishedAt"]},"CreateReleaseRequest":{"type":"object","properties":{"version":{"type":"string","minLength":1,"example":"1.4.0"},"notes":{"type":"string","description":"release notes (markdown)"},"netProtocol":{"type":"string","description":"client/server compatibility marker surfaced on download pages","example":"42"},"meta":{"$ref":"#/components/schemas/ReleaseMeta"}},"required":["version"]},"ReleaseMeta":{"type":"object","additionalProperties":{},"description":"structured release metadata — a JSON object, ≤ 8 KiB serialized","example":{"godotVersion":"4.3.stable"}},"ReleaseArtifact":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"releaseId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["build","content","map"]},"tags":{"type":"array","items":{"type":"string"}},"filename":{"type":"string"},"extractTo":{"type":"string"},"required":{"type":"boolean"},"platform":{"type":["string","null"]},"sort":{"type":"integer"},"blobId":{"type":"string","format":"uuid"}},"required":["id","releaseId","kind","tags","filename","extractTo","required","platform","sort","blobId"]},"AttachArtifactRequest":{"type":"object","properties":{"kind":{"type":"string","enum":["build","content","map"]},"tags":{"type":"array","items":{"type":"string"},"example":["valve"]},"filename":{"type":"string","minLength":1,"example":"cs3.exe"},"extractTo":{"type":"string","description":"install-relative extract path"},"required":{"type":"boolean"},"platform":{"type":"string","example":"windows"},"sort":{"type":"integer"},"blobId":{"type":"string","format":"uuid","description":"a prepared blob (may still be verifying)"}},"required":["kind","filename","blobId"]},"PublishRequest":{"type":"object","properties":{"channel":{"type":"string","description":"optionally move this channel's pointer to the release in the same transaction","example":"dev"}}},"Channel":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"projectId":{"type":"string","format":"uuid"},"name":{"type":"string"},"currentReleaseId":{"type":["string","null"],"format":"uuid"}},"required":["id","projectId","name","currentReleaseId"]},"PromoteRequest":{"type":"object","properties":{"releaseId":{"type":"string","format":"uuid"}},"required":["releaseId"]},"RetentionPolicy":{"type":"object","properties":{"mode":{"$ref":"#/components/schemas/RetentionMode"},"count":{"type":["integer","null"],"description":"keep_last_n / keep_n_or_days count"},"days":{"type":["integer","null"],"description":"keep_days / keep_n_or_days window"},"archiveGraceDays":{"type":["integer","null"],"description":"null = archive-only; 0 = hard-delete immediately; N = N days after archival"}},"required":["mode","count","days","archiveGraceDays"]},"RetentionMode":{"type":"string","enum":["keep_all","keep_last_n","keep_days","keep_n_or_days"]},"SetRetentionRequest":{"type":"object","properties":{"retention_mode":{"$ref":"#/components/schemas/RetentionMode"},"retention_count":{"type":["integer","null"],"exclusiveMinimum":0},"retention_days":{"type":["integer","null"],"exclusiveMinimum":0},"archive_grace_days":{"type":["integer","null"],"minimum":0}},"required":["retention_mode"]},"RetentionPreview":{"type":"object","properties":{"wouldArchive":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"version":{"type":"string"}},"required":["id","version"]}},"wouldDeleteSoon":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"version":{"type":"string"}},"required":["id","version"]}}},"required":["wouldArchive","wouldDeleteSoon"]},"RetentionApplyResult":{"type":"object","properties":{"archived":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["archived"]},"ReleaseList":{"type":"object","properties":{"releases":{"type":"array","items":{"$ref":"#/components/schemas/ReleaseListItem"}},"nextCursor":{"type":["string","null"],"description":"opaque cursor; null when exhausted"}},"required":["releases","nextCursor"]},"ReleaseListItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"version":{"type":"string"},"status":{"type":"string","enum":["draft","published"]},"notes":{"type":["string","null"]},"netProtocol":{"type":["string","null"]},"meta":{"type":["object","null"],"additionalProperties":{}},"publishedAt":{"type":["string","null"]},"createdAt":{"type":"string"},"archivedAt":{"type":["string","null"],"description":"retention tombstone; non-null iff the release is archived"},"artifactCount":{"type":"integer"},"channelsPointing":{"type":"array","items":{"type":"string"},"description":"names of the channels whose pointer currently resolves to this release"},"allVerified":{"type":"boolean","description":"true iff the release has ≥1 artifact and every artifact's blob is verified"}},"required":["id","version","status","notes","netProtocol","meta","publishedAt","createdAt","archivedAt","artifactCount","channelsPointing","allVerified"]},"ReleaseDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"version":{"type":"string"},"status":{"type":"string","enum":["draft","published"]},"notes":{"type":["string","null"]},"netProtocol":{"type":["string","null"]},"meta":{"type":["object","null"],"additionalProperties":{}},"publishedAt":{"type":["string","null"]},"createdAt":{"type":"string"},"archivedAt":{"type":["string","null"]},"channelsPointing":{"type":"array","items":{"type":"string"}},"allVerified":{"type":"boolean"},"artifacts":{"type":"array","items":{"$ref":"#/components/schemas/ReleaseDetailArtifact"}},"createdBy":{"type":["object","null"],"properties":{"id":{"type":"string"},"label":{"type":"string"}},"required":["id","label"]},"activity":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string"},"actorLabel":{"type":"string"},"at":{"type":"string"}},"required":["action","actorLabel","at"]}}},"required":["id","version","status","notes","netProtocol","meta","publishedAt","createdAt","archivedAt","channelsPointing","allVerified","artifacts","createdBy","activity"]},"ReleaseDetailArtifact":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"filename":{"type":"string"},"size":{"type":"integer"},"sha256":{"type":["string","null"]},"blobStatus":{"type":"string","enum":["staged","verified"]}},"required":["id","filename","size","sha256","blobStatus"]},"ChannelList":{"type":"object","properties":{"channels":{"type":"array","items":{"$ref":"#/components/schemas/ChannelListItem"}}},"required":["channels"]},"ChannelListItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"currentReleaseId":{"type":["string","null"],"format":"uuid"},"currentVersion":{"type":["string","null"]},"retention":{"$ref":"#/components/schemas/RetentionPolicy"}},"required":["id","name","currentReleaseId","currentVersion","retention"]},"ReleaseManifest":{"type":"object","properties":{"release":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"version":{"type":"string"},"notes":{"type":["string","null"]},"netProtocol":{"type":["string","null"]},"meta":{"type":["object","null"],"additionalProperties":{}},"status":{"type":"string","enum":["draft","published"]},"publishedAt":{"type":["string","null"]}},"required":["id","version","notes","netProtocol","meta","status","publishedAt"]},"artifacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["build","content","map"]},"tags":{"type":"array","items":{"type":"string"}},"filename":{"type":"string"},"extractTo":{"type":"string"},"required":{"type":"boolean"},"platform":{"type":["string","null"]},"sort":{"type":"integer"},"size":{"type":"integer"},"sha256":{"type":["string","null"]},"blobId":{"type":"string","format":"uuid"}},"required":["id","kind","tags","filename","extractTo","required","platform","sort","size","sha256","blobId"]}}},"required":["release","artifacts"]},"ChannelManifest":{"type":"object","properties":{"channel":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]},"releaseId":{"type":"string","format":"uuid"},"release":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"version":{"type":"string"},"notes":{"type":["string","null"]},"netProtocol":{"type":["string","null"]},"meta":{"type":["object","null"],"additionalProperties":{}},"status":{"type":"string","enum":["draft","published"]},"publishedAt":{"type":["string","null"]}},"required":["id","version","notes","netProtocol","meta","status","publishedAt"]},"artifacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["build","content","map"]},"tags":{"type":"array","items":{"type":"string"}},"filename":{"type":"string"},"extractTo":{"type":"string"},"required":{"type":"boolean"},"platform":{"type":["string","null"]},"sort":{"type":"integer"},"size":{"type":"integer"},"sha256":{"type":["string","null"]},"blobId":{"type":"string","format":"uuid"}},"required":["id","kind","tags","filename","extractTo","required","platform","sort","size","sha256","blobId"]}}},"required":["channel","releaseId","release","artifacts"]},"DownloadUrl":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"presigned GET; egress recorded at issue time"},"expiresAt":{"type":"string"}},"required":["url","expiresAt"]},"Page":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"projectId":{"type":"string","format":"uuid"},"slug":{"type":"string"},"template":{"type":"string","enum":["game","minimal","bundle"]},"theme":{"$ref":"#/components/schemas/PageTheme"},"sections":{"type":["array","null"],"items":{"$ref":"#/components/schemas/PageSection"}},"visibility":{"type":"string","enum":["private","public"]}},"required":["id","projectId","slug","template","theme","sections","visibility"]},"PageTheme":{"type":["object","null"],"properties":{"logoBlobId":{"type":"string","format":"uuid"},"heroBlobId":{"type":"string","format":"uuid"},"accentColor":{"type":"string","example":"#00ff88"}}},"PageSection":{"type":"object","properties":{"title":{"type":"string"},"body":{"type":"string","description":"owner-authored markdown"}},"required":["body"]},"CreatePageRequest":{"type":"object","properties":{"template":{"type":"string","enum":["game","minimal","bundle"]},"theme":{"$ref":"#/components/schemas/PageTheme"},"sections":{"type":["array","null"],"items":{"$ref":"#/components/schemas/PageSection"}},"visibility":{"type":"string","enum":["private","public"]}}},"UpdatePageRequest":{"type":"object","properties":{"template":{"type":"string","enum":["game","minimal","bundle"]},"theme":{"$ref":"#/components/schemas/PageTheme"},"sections":{"type":["array","null"],"items":{"$ref":"#/components/schemas/PageSection"}},"visibility":{"type":"string","enum":["private","public"]}}},"PageItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"pageId":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":["string","null"]},"sort":{"type":"integer"},"selector":{"type":"object","properties":{"kind":{"type":"string","enum":["build","content","map"]},"tags":{"type":"array","items":{"type":"string"}},"glob":{"type":["string","null"]}},"required":["kind","tags","glob"]},"pin":{"type":"object","properties":{"channelId":{"type":["string","null"],"format":"uuid"},"releaseId":{"type":["string","null"],"format":"uuid"}},"required":["channelId","releaseId"]}},"required":["id","pageId","title","description","sort","selector","pin"]},"CreatePageItemRequest":{"type":"object","properties":{"title":{"type":"string","minLength":1},"description":{"type":["string","null"]},"sort":{"type":"integer"},"selector":{"$ref":"#/components/schemas/PageSelector"},"pin":{"$ref":"#/components/schemas/PagePin"}},"required":["title","selector","pin"]},"PageSelector":{"type":"object","properties":{"kind":{"type":"string","enum":["build","content","map"]},"tags":{"type":"array","items":{"type":"string"},"example":["valve"]},"glob":{"type":["string","null"],"description":"minimal glob on filename: * (any run) / ? (one char)"}},"required":["kind"]},"PagePin":{"type":"object","properties":{"channelId":{"type":"string","format":"uuid"},"releaseId":{"type":"string","format":"uuid"}},"description":"track a channel (channelId) XOR pin a release (releaseId)"},"UpdatePageItemRequest":{"type":"object","properties":{"title":{"type":"string","minLength":1},"description":{"type":["string","null"]},"sort":{"type":"integer"},"selector":{"$ref":"#/components/schemas/PageSelector"},"pin":{"$ref":"#/components/schemas/PagePin"}}},"PageWithItems":{"type":"object","properties":{"page":{"$ref":"#/components/schemas/Page"},"items":{"type":"array","items":{"$ref":"#/components/schemas/PageItem"}}},"required":["page","items"]},"PageManifest":{"type":"object","properties":{"page":{"type":"object","properties":{"slug":{"type":"string"},"template":{"type":"string","enum":["game","minimal","bundle"]},"theme":{"$ref":"#/components/schemas/PageTheme"},"sections":{"type":["array","null"],"items":{"$ref":"#/components/schemas/PageSection"}},"visibility":{"type":"string","enum":["private","public"]}},"required":["slug","template","theme","sections","visibility"]},"items":{"type":"array","items":{"type":"object","properties":{"item":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":["string","null"]},"sort":{"type":"integer"},"selector":{"type":"object","properties":{"kind":{"type":"string","enum":["build","content","map"]},"tags":{"type":"array","items":{"type":"string"}},"glob":{"type":["string","null"]}},"required":["kind","tags","glob"]}},"required":["id","title","description","sort","selector"]},"resolution":{"type":"object","properties":{"mode":{"type":"string","enum":["pinned","tracking"]},"channelName":{"type":["string","null"]},"releaseId":{"type":["string","null"],"format":"uuid"},"version":{"type":["string","null"]},"publishedAt":{"type":["string","null"]}},"required":["mode","channelName","releaseId","version","publishedAt"]},"artifacts":{"type":"array","items":{"type":"object","properties":{"artifactId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["build","content","map"]},"tags":{"type":"array","items":{"type":"string"}},"filename":{"type":"string"},"extractTo":{"type":"string"},"required":{"type":"boolean"},"platform":{"type":["string","null"]},"sort":{"type":"integer"},"size":{"type":"integer"},"sha256":{"type":["string","null"]},"blobId":{"type":"string","format":"uuid"}},"required":["artifactId","kind","tags","filename","extractTo","required","platform","sort","size","sha256","blobId"]}}},"required":["item","resolution","artifacts"]}}},"required":["page","items"]},"SpaceList":{"type":"object","properties":{"spaces":{"type":"array","items":{"$ref":"#/components/schemas/Space"}}},"required":["spaces"]},"Space":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["personal","shared"]},"ownerUserId":{"type":["string","null"]},"ownerOrgId":{"type":["string","null"]},"name":{"type":"string"},"visibility":{"type":"string","enum":["private","public"]}},"required":["id","kind","ownerUserId","ownerOrgId","name","visibility"]},"CreateSpaceRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"example":"Asset Packs"},"visibility":{"type":"string","enum":["private","public"],"description":"defaults to private"}},"required":["name"]},"SpaceDetails":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["personal","shared"]},"name":{"type":"string"},"visibility":{"type":"string","enum":["private","public"]},"ownerUserId":{"type":["string","null"]},"ownerOrgId":{"type":["string","null"]},"createdAt":{"type":"string"},"createdBy":{"type":["object","null"],"properties":{"id":{"type":"string"},"label":{"type":"string"}},"required":["id","label"]},"activity":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string"},"actorLabel":{"type":"string"},"at":{"type":"string"}},"required":["action","actorLabel","at"]}}},"required":["id","kind","name","visibility","ownerUserId","ownerOrgId","createdAt","createdBy","activity"]},"UpdateSpaceRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1},"visibility":{"type":"string","enum":["private","public"]}}},"PrepareFileRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"example":"synty-pack.zip"},"folderPath":{"type":"string","description":"materialized folder path, e.g. /asset-packs/synty","example":"/"},"size":{"type":"integer","minimum":0,"maximum":5497558138880,"example":5368709120},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"optional hash claim — the Drive no-claim path omits it","example":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}},"required":["name","size"]},"FileList":{"type":"object","properties":{"files":{"type":"array","items":{"$ref":"#/components/schemas/File"}}},"required":["files"]},"File":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"spaceId":{"type":"string","format":"uuid"},"name":{"type":"string"},"folderPath":{"type":"string"},"blobId":{"type":"string","format":"uuid"},"uploadedBy":{"type":["string","null"]},"createdAt":{"type":"string"},"size":{"type":"integer"},"sha256":{"type":["string","null"]},"blobStatus":{"type":"string","enum":["staged","verified"]},"shareState":{"type":"string","enum":["active","inactive","none"]}},"required":["id","spaceId","name","folderPath","blobId","uploadedBy","createdAt","size","sha256","blobStatus","shareState"]},"FolderListing":{"type":"object","properties":{"files":{"type":"array","items":{"$ref":"#/components/schemas/File"}},"folders":{"type":"array","items":{"type":"string"},"description":"immediate subfolder names"},"nextCursor":{"type":["string","null"],"description":"opaque cursor; null when exhausted"}},"required":["files","folders","nextCursor"]},"FileSearchResult":{"type":"object","properties":{"files":{"type":"array","items":{"$ref":"#/components/schemas/File"}},"nextCursor":{"type":["string","null"]}},"required":["files","nextCursor"]},"UpdateFileRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1},"folderPath":{"type":"string","description":"materialized folder path, e.g. /asset-packs/synty","example":"/"}}},"MoveFolderResult":{"type":"object","properties":{"moved":{"type":"integer"}},"required":["moved"]},"MoveFolderRequest":{"type":"object","properties":{"fromPath":{"type":"string","description":"materialized folder path, e.g. /asset-packs/synty","example":"/asset-packs"},"toPath":{"type":"string","description":"materialized folder path, e.g. /asset-packs/synty","example":"/archive/asset-packs"}},"required":["fromPath","toPath"]},"FileDetails":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"spaceId":{"type":"string","format":"uuid"},"name":{"type":"string"},"folderPath":{"type":"string"},"createdAt":{"type":"string"},"uploadedBy":{"type":["string","null"]},"uploaderName":{"type":["string","null"]},"uploaderEmail":{"type":["string","null"]},"blobId":{"type":"string","format":"uuid"},"sha256":{"type":["string","null"]},"size":{"type":"integer"},"blobStatus":{"type":"string","enum":["staged","verified"]},"s3Key":{"type":"string"},"fileRefCount":{"type":"integer"},"artifactRefCount":{"type":"integer"},"otherRefCount":{"type":"integer"},"downloadCount":{"type":"integer"},"activity":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string"},"actorLabel":{"type":"string"},"at":{"type":"string"}},"required":["action","actorLabel","at"]}}},"required":["id","spaceId","name","folderPath","createdAt","uploadedBy","uploaderName","uploaderEmail","blobId","sha256","size","blobStatus","s3Key","fileRefCount","artifactRefCount","otherRefCount","downloadCount","activity"]},"CreatedShareLink":{"allOf":[{"$ref":"#/components/schemas/ShareLink"},{"type":"object","properties":{"token":{"type":"string","description":"url-safe secret; exercise via x-depot-share-token. Returned ONLY here, at creation — never again on list/detail."}},"required":["token"]}]},"ShareLinkScope":{"type":"string","enum":["project","channel","release","page","space","folder","file"]},"ShareLink":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"scope":{"$ref":"#/components/schemas/ShareLinkScope"},"organizationId":{"type":["string","null"]},"projectId":{"type":["string","null"],"format":"uuid"},"channelId":{"type":["string","null"],"format":"uuid"},"releaseId":{"type":["string","null"],"format":"uuid"},"pageId":{"type":["string","null"],"format":"uuid"},"spaceId":{"type":["string","null"],"format":"uuid"},"fileId":{"type":["string","null"],"format":"uuid"},"folderPath":{"type":["string","null"]},"expiresAt":{"type":["string","null"]},"maxUses":{"type":["integer","null"]},"uses":{"type":"integer"},"revoked":{"type":"boolean"},"createdAt":{"type":"string"}},"required":["id","scope","organizationId","projectId","channelId","releaseId","pageId","spaceId","fileId","folderPath","expiresAt","maxUses","uses","revoked","createdAt"]},"CreateProjectShareLinkRequest":{"type":"object","properties":{"scope":{"type":"string","enum":["project","channel","release","page"],"description":"which project-side surface the link grants read of"},"channelName":{"type":"string","description":"required for scope=channel"},"releaseId":{"type":"string","format":"uuid","description":"required for scope=release"},"expiresAt":{"type":"string","format":"date-time","description":"optional ISO-8601 expiry"},"maxUses":{"type":"integer","exclusiveMinimum":0,"description":"optional exercise cap (atomic; no over-issue)"}},"required":["scope"]},"ShareLinkList":{"type":"object","properties":{"links":{"type":"array","items":{"$ref":"#/components/schemas/ShareLink"}}},"required":["links"]},"CreateDriveShareLinkRequest":{"type":"object","properties":{"scope":{"type":"string","enum":["space","folder","file"]},"folderPath":{"type":"string","description":"required for scope=folder","example":"/"},"fileId":{"type":"string","format":"uuid","description":"required for scope=file"},"expiresAt":{"type":"string","format":"date-time"},"maxUses":{"type":"integer","exclusiveMinimum":0}},"required":["scope"]},"MyShareLinkList":{"type":"object","properties":{"links":{"type":"array","items":{"$ref":"#/components/schemas/MyShareLink"}},"nextCursor":{"type":["string","null"],"description":"opaque cursor; null when exhausted"}},"required":["links","nextCursor"]},"MyShareLink":{"allOf":[{"$ref":"#/components/schemas/ShareLink"},{"type":"object","properties":{"label":{"type":"string","example":"file report.bin in Personal"},"subjectName":{"type":"string","description":"the shared thing itself (file/channel/space name, version, path)","example":"report.bin"},"subjectLocation":{"type":["string","null"],"description":"where the subject lives (parent project/space), null for top-level subjects","example":"Personal"}},"required":["label","subjectName","subjectLocation"]}]},"ProjectList":{"type":"object","properties":{"projects":{"type":"array","items":{"$ref":"#/components/schemas/Project"}}},"required":["projects"]},"Project":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"visibility":{"type":"string","enum":["private","public"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","organizationId","slug","name","visibility","createdAt","updatedAt"]},"CreateProjectRequest":{"type":"object","properties":{"slug":{"type":"string","minLength":1,"description":"url slug: lowercase letters/numbers/hyphens, unique per org","example":"cs3"},"name":{"type":"string","minLength":1,"example":"cs3"},"visibility":{"type":"string","enum":["private","public"],"description":"defaults to private"}},"required":["slug","name"]},"UpdateProjectRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1},"visibility":{"type":"string","enum":["private","public"]}}},"AdminUserList":{"type":"object","properties":{"users":{"type":"array","items":{"$ref":"#/components/schemas/AdminUser"}},"nextCursor":{"type":["string","null"],"description":"opaque cursor; null when exhausted"}},"required":["users","nextCursor"]},"AdminUser":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"role":{"type":["string","null"],"description":"BetterAuth site role (admin|user)"},"banned":{"type":"boolean"},"createdAt":{"type":"string"}},"required":["id","email","name","role","banned","createdAt"]},"CreateUserRequest":{"type":"object","properties":{"email":{"type":"string","format":"email"},"name":{"type":"string","minLength":1},"password":{"type":"string","minLength":8,"description":"initial password, handed over out-of-band"},"siteAdmin":{"type":"boolean","description":"grant the BetterAuth site-admin role (can manage users)"},"organizationId":{"type":"string","minLength":1,"description":"if set (with orgRole), add the new user to THIS org"},"orgRole":{"$ref":"#/components/schemas/OrgRole"}},"required":["email","name","password"]},"OrgRole":{"type":"string","enum":["owner","admin","publisher"],"description":"if set (with organizationId), add the new user to that org with this role"},"UpdateUserRequest":{"type":"object","properties":{"role":{"type":"string","enum":["admin","user"],"description":"site role: admin (can manage users) or user"},"banned":{"type":"boolean","description":"true disables the account and revokes its sessions"}}},"OrgMemberList":{"type":"object","properties":{"members":{"type":"array","items":{"$ref":"#/components/schemas/OrgMember"}}},"required":["members"]},"OrgMember":{"type":"object","properties":{"userId":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"role":{"type":"string"},"createdAt":{"type":"string"}},"required":["userId","email","name","role","createdAt"]},"OrgList":{"type":"object","properties":{"organizations":{"type":"array","items":{"$ref":"#/components/schemas/OrgSummary"}}},"required":["organizations"]},"OrgSummary":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"role":{"allOf":[{"$ref":"#/components/schemas/OrgRole"},{"description":"the caller's role in this org"}]},"projectCount":{"type":"integer"},"spaceCount":{"type":"integer"}},"required":["id","name","slug","role","projectCount","spaceCount"]},"OrgOverview":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"role":{"$ref":"#/components/schemas/OrgRole"},"projects":{"type":"array","items":{"$ref":"#/components/schemas/OrgProjectSummary"}},"spaces":{"type":"array","items":{"$ref":"#/components/schemas/OrgSpaceSummary"}}},"required":["id","name","slug","role","projects","spaces"]},"OrgProjectSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"visibility":{"type":"string","enum":["private","public"]}},"required":["id","slug","name","visibility"]},"OrgSpaceSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"visibility":{"type":"string","enum":["private","public"]}},"required":["id","name","visibility"]},"RenameOrgRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1}},"required":["name"]},"AddMemberRequest":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"an EXISTING depot user's email"},"role":{"$ref":"#/components/schemas/OrgRole"}},"required":["email","role"]},"SetMemberRoleRequest":{"type":"object","properties":{"role":{"$ref":"#/components/schemas/OrgRole"}},"required":["role"]},"ApiKeyList":{"type":"object","properties":{"keys":{"type":"array","items":{"$ref":"#/components/schemas/ApiKeyListItem"}}},"required":["keys"]},"ApiKeyListItem":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"preset":{"$ref":"#/components/schemas/ApiKeyPreset"},"permissions":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"start":{"type":["string","null"],"description":"non-secret key prefix for display"},"enabled":{"type":"boolean"},"rateLimitMax":{"type":["integer","null"]},"createdAt":{"type":"string"},"expiresAt":{"type":["string","null"]},"lastRequest":{"type":["string","null"],"description":"native last-used tracking"}},"required":["id","name","preset","permissions","start","enabled","rateLimitMax","createdAt","expiresAt","lastRequest"]},"ApiKeyPreset":{"type":["string","null"],"enum":["read-only","publish","full",null],"description":"read-only (project:read) · publish (project:read + release:create/publish) · full (org-management scope)"},"CreatedApiKey":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string","description":"the secret — shown once, never retrievable again"},"name":{"type":"string"},"preset":{"$ref":"#/components/schemas/ApiKeyPreset"},"permissions":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"expiresAt":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","key","name","preset","permissions","expiresAt","createdAt"]},"CreateApiKeyRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"example":"cs3-ci"},"preset":{"$ref":"#/components/schemas/ApiKeyPreset"},"expiresInDays":{"type":"integer","exclusiveMinimum":0,"description":"optional expiry, in days from now"},"rateLimitPerMinute":{"type":"integer","exclusiveMinimum":0,"description":"optional per-key rate limit (max requests/minute)"}},"required":["name","preset"]},"AuditPage":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/AuditEvent"}},"nextCursor":{"type":["string","null"],"description":"opaque cursor; null when exhausted"}},"required":["events","nextCursor"]},"AuditEvent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"at":{"type":"string"},"action":{"type":"string"},"actorType":{"$ref":"#/components/schemas/AuditActorType"},"actorId":{"type":"string"},"actorLabel":{"type":"string","description":"resolved display name where the actor is a user"},"subject":{"type":"string"},"subjectType":{"type":"string"},"subjectLabel":{"type":"string","description":"readable subject label (slug/version/name)"},"metadata":{"type":["object","null"],"additionalProperties":{}}},"required":["id","at","action","actorType","actorId","actorLabel","subject","subjectType","subjectLabel","metadata"]},"AuditActorType":{"type":"string","enum":["user","api_key","share_link","system"]},"Me":{"type":"object","properties":{"kind":{"type":"string","enum":["user","api_key","share_link"]},"userId":{"type":"string"},"email":{"type":"string"},"organizationId":{"type":["string","null"]},"apiKeyId":{"type":"string"},"scope":{"type":["string","null"],"enum":["personal","org",null],"description":"api-key only: descriptive scope from key metadata"},"role":{"type":["string","null"],"description":"api-key only: the key owner's role in organizationId"}},"required":["kind","organizationId"]},"SessionList":{"type":"object","properties":{"sessions":{"type":"array","items":{"$ref":"#/components/schemas/Session"}}},"required":["sessions"]},"Session":{"type":"object","properties":{"id":{"type":"string"},"current":{"type":"boolean","description":"true for the session making this request"},"device":{"type":"string","description":"parsed from the user-agent, e.g. Chrome on Windows"},"ip":{"type":["string","null"]},"createdAt":{"type":"string"},"lastActive":{"type":"string","description":"updatedAt — bumped by rolling refresh"},"expiresAt":{"type":"string"}},"required":["id","current","device","ip","createdAt","lastActive","expiresAt"]},"RevokeOthersResult":{"type":"object","properties":{"revoked":{"type":"integer"}},"required":["revoked"]},"CreatePersonalApiKeyRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"example":"laptop-cli"},"preset":{"$ref":"#/components/schemas/PersonalApiKeyPreset"},"expiresInDays":{"type":"integer","exclusiveMinimum":0,"maximum":365,"description":"optional expiry in days (default 90, max 365)"}},"required":["name","preset"]},"PersonalApiKeyPreset":{"type":"string","enum":["read-only","publish","full"],"description":"The org presets minus apikey:* — read-only (project:read + space:read) · publish (+ release:create/publish) · full (project CRUD, release create/publish/read, space read/write). Org-less by default; acts inside an org selected per request via the x-depot-org header, capped by the owner's role there. Never mints tokens."},"SearchResults":{"type":"object","properties":{"orgs":{"type":"object","properties":{"hits":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"location":{"type":["string","null"]},"href":{"type":"string","description":"in-app deep link to jump to (incl. Drive ?path=)"}},"required":["id","name","location","href"]}},"hasMore":{"type":"boolean"}},"required":["hits","hasMore"]},"projects":{"type":"object","properties":{"hits":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"location":{"type":["string","null"]},"href":{"type":"string","description":"in-app deep link to jump to (incl. Drive ?path=)"}},"required":["id","name","location","href"]}},"hasMore":{"type":"boolean"}},"required":["hits","hasMore"]},"spaces":{"type":"object","properties":{"hits":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"location":{"type":["string","null"]},"href":{"type":"string","description":"in-app deep link to jump to (incl. Drive ?path=)"}},"required":["id","name","location","href"]}},"hasMore":{"type":"boolean"}},"required":["hits","hasMore"]},"folders":{"type":"object","properties":{"hits":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"location":{"type":["string","null"]},"href":{"type":"string","description":"in-app deep link to jump to (incl. Drive ?path=)"}},"required":["id","name","location","href"]}},"hasMore":{"type":"boolean"}},"required":["hits","hasMore"]},"files":{"type":"object","properties":{"hits":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"location":{"type":["string","null"]},"href":{"type":"string","description":"in-app deep link to jump to (incl. Drive ?path=)"}},"required":["id","name","location","href"]}},"hasMore":{"type":"boolean"}},"required":["hits","hasMore"]}},"required":["orgs","projects","spaces","folders","files"]}},"parameters":{}},"paths":{"/api/v1/blobs/prepare":{"post":{"summary":"Prepare a blob upload (optional hash claim)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrepareRequest"}}}},"responses":{"200":{"description":"Dedupe hit ({exists}) or a new multipart upload session ({upload})","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrepareResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Too many in-flight upload sessions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Size exceeds the maximum, or org storage quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Upload issuance rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/blobs/sessions/{id}/complete":{"post":{"summary":"Complete a multipart upload and enqueue verification","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteRequest"}}}},"responses":{"200":{"description":"Upload completed; verify job enqueued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Session in a non-completable state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Upload issuance rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects/{project}/releases":{"post":{"summary":"Create a draft release (version unique per project)","parameters":[{"schema":{"type":"string","example":"cs3"},"required":true,"name":"project","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateReleaseRequest"}}}},"responses":{"201":{"description":"Draft created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Release"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Version already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List releases newest-first (?version exact lookup, ?status filter, paginated)","parameters":[{"schema":{"type":"string","example":"cs3"},"required":true,"name":"project","in":"path"},{"schema":{"type":"string","description":"exact-version lookup"},"required":false,"description":"exact-version lookup","name":"version","in":"query"},{"schema":{"type":"string","minLength":1,"description":"case-insensitive substring over version or notes"},"required":false,"description":"case-insensitive substring over version or notes","name":"q","in":"query"},{"schema":{"type":"string","enum":["draft","published"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","exclusiveMinimum":0},"required":false,"name":"limit","in":"query"},{"schema":{"type":["boolean","null"],"description":"include retention-archived releases (org members only)"},"required":false,"description":"include retention-archived releases (org members only)","name":"includeArchived","in":"query"}],"responses":{"200":{"description":"A page of releases (newest-first)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReleaseList"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects/{project}/releases/{id}/artifacts":{"post":{"summary":"Attach an artifact to a draft (blob may still be verifying)","parameters":[{"schema":{"type":"string","example":"cs3"},"required":true,"name":"project","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachArtifactRequest"}}}},"responses":{"201":{"description":"Attached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReleaseArtifact"}}}},"400":{"description":"Invalid extract_to/filename","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Release or blob not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Release is published (immutable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects/{project}/releases/{id}/artifacts/{artifactId}":{"delete":{"summary":"Detach an artifact from a draft","parameters":[{"schema":{"type":"string","example":"cs3"},"required":true,"name":"project","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"artifactId","in":"path"}],"responses":{"200":{"description":"Detached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Release is published (immutable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects/{project}/releases/{id}":{"delete":{"summary":"Delete a draft release","parameters":[{"schema":{"type":"string","example":"cs3"},"required":true,"name":"project","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Release is published (immutable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects/{project}/releases/{id}/publish":{"post":{"summary":"Publish a draft (refuses unverified blobs; optional publish-to-channel)","parameters":[{"schema":{"type":"string","example":"cs3"},"required":true,"name":"project","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishRequest"}}}},"responses":{"200":{"description":"Published","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Release"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Not a draft, or blobs unverified","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects/{project}/channels/{name}/promote":{"post":{"summary":"Promote a channel pointer to a published release (zero bytes)","parameters":[{"schema":{"type":"string","example":"cs3"},"required":true,"name":"project","in":"path"},{"schema":{"type":"string","example":"dev"},"required":true,"name":"name","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromoteRequest"}}}},"responses":{"200":{"description":"Promoted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Channel"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Project or release not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Release is a draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects/{project}/channels/{name}/retention":{"get":{"summary":"Read a channel's build-retention policy (owner/admin only)","parameters":[{"schema":{"type":"string","example":"cs3"},"required":true,"name":"project","in":"path"},{"schema":{"type":"string","example":"dev"},"required":true,"name":"name","in":"path"}],"responses":{"200":{"description":"The channel's retention policy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetentionPolicy"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Requires an org owner/admin","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Project or channel not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Set a channel's build-retention policy (owner/admin only)","parameters":[{"schema":{"type":"string","example":"cs3"},"required":true,"name":"project","in":"path"},{"schema":{"type":"string","example":"dev"},"required":true,"name":"name","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetRetentionRequest"}}}},"responses":{"200":{"description":"Updated policy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetentionPolicy"}}}},"400":{"description":"Invalid policy (mode/parameter mismatch)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Requires an org owner/admin","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Project or channel not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Invalid policy state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects/{project}/channels/{name}/retention/preview":{"get":{"summary":"Dry-run: what retention would archive / hard-delete soon (owner/admin only)","parameters":[{"schema":{"type":"string","example":"cs3"},"required":true,"name":"project","in":"path"},{"schema":{"type":"string","example":"dev"},"required":true,"name":"name","in":"path"}],"responses":{"200":{"description":"Dry-run result (mutates nothing)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetentionPreview"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Requires an org owner/admin","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Project or channel not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects/{project}/channels/{name}/retention/apply":{"post":{"summary":"Run a channel's retention now — archive prune-eligible releases (owner/admin only)","parameters":[{"schema":{"type":"string","example":"cs3"},"required":true,"name":"project","in":"path"},{"schema":{"type":"string","example":"dev"},"required":true,"name":"name","in":"path"}],"responses":{"200":{"description":"Archived release ids","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetentionApplyResult"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Requires an org owner/admin","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Project or channel not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects/{project}/releases/{version}/restore":{"post":{"summary":"Restore an archived release (owner/admin only; refused once hard-deleted)","parameters":[{"schema":{"type":"string","example":"cs3"},"required":true,"name":"project","in":"path"},{"schema":{"type":"string","example":"1.4.0"},"required":true,"name":"version","in":"path"}],"responses":{"200":{"description":"Restored","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Requires an org owner/admin","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Project or release not found (or already hard-deleted)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Release is not archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects/{project}/releases/{version}":{"get":{"summary":"Get one release by version with its artifacts (row-expand detail)","parameters":[{"schema":{"type":"string","example":"cs3"},"required":true,"name":"project","in":"path"},{"schema":{"type":"string","example":"1.4.0"},"required":true,"name":"version","in":"path"}],"responses":{"200":{"description":"The release + its artifacts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReleaseDetail"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Project or release not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects/{project}/channels":{"get":{"summary":"List channels with their resolved current version","parameters":[{"schema":{"type":"string","example":"cs3"},"required":true,"name":"project","in":"path"}],"responses":{"200":{"description":"The project's channels","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelList"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects/{project}/releases/{id}/manifest":{"get":{"summary":"Release manifest (published only) — artifact metadata + hashes","parameters":[{"schema":{"type":"string","example":"cs3"},"required":true,"name":"project","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Manifest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReleaseManifest"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found or not published","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects/{project}/channels/{name}/manifest":{"get":{"summary":"Channel manifest — resolves the pointer to its published release","parameters":[{"schema":{"type":"string","example":"cs3"},"required":true,"name":"project","in":"path"},{"schema":{"type":"string","example":"dev"},"required":true,"name":"name","in":"path"}],"responses":{"200":{"description":"Manifest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelManifest"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Channel unset or project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects/{project}/releases/{id}/artifacts/{artifactId}/download":{"get":{"summary":"Issue a presigned GET for one artifact (egress recorded at issue time)","parameters":[{"schema":{"type":"string","example":"cs3"},"required":true,"name":"project","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"artifactId","in":"path"}],"responses":{"200":{"description":"Download URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DownloadUrl"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found or not published","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Presign issuance rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects/{project}/page":{"post":{"summary":"Create the project's landing page (one per project; slug = project slug)","parameters":[{"schema":{"type":"string","example":"cs3"},"required":true,"name":"project","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePageRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}},"400":{"description":"Invalid theme or sections","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A page already exists for this project","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update the project's landing page (template, theme, sections, visibility)","parameters":[{"schema":{"type":"string","example":"cs3"},"required":true,"name":"project","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePageRequest"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}},"400":{"description":"Invalid theme or sections","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Project or page not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete the project's landing page (items cascade)","parameters":[{"schema":{"type":"string","example":"cs3"},"required":true,"name":"project","in":"path"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Project or page not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects/{project}/page/items":{"post":{"summary":"Add a curated item (selector + pin: track a channel XOR pin a release)","parameters":[{"schema":{"type":"string","example":"cs3"},"required":true,"name":"project","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePageItemRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageItem"}}}},"400":{"description":"Invalid pin (not exactly one of channel/release)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Project, page, channel, or release not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Cannot pin a draft release","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects/{project}/page/items/{itemId}":{"patch":{"summary":"Update a curated item — flipping track→pin is the per-item rollback","parameters":[{"schema":{"type":"string","example":"cs3"},"required":true,"name":"project","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"itemId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePageItemRequest"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageItem"}}}},"400":{"description":"Invalid pin","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Cannot pin a draft release","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Remove a curated item","parameters":[{"schema":{"type":"string","example":"cs3"},"required":true,"name":"project","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"itemId","in":"path"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/pages/{slug}":{"get":{"summary":"The landing page + items UNRESOLVED (the future editor UI)","parameters":[{"schema":{"type":"string","example":"cs3"},"required":true,"name":"slug","in":"path"}],"responses":{"200":{"description":"Page + items","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageWithItems"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/pages/{slug}/manifest":{"get":{"summary":"The launcher contract — items resolved to concrete artifacts + hashes","parameters":[{"schema":{"type":"string","example":"cs3"},"required":true,"name":"slug","in":"path"}],"responses":{"200":{"description":"Resolved page manifest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageManifest"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/pages/{slug}/items/{itemId}/artifacts/{artifactId}/download":{"get":{"summary":"Presigned GET through the page context (records the item — per-item counts)","parameters":[{"schema":{"type":"string","example":"cs3"},"required":true,"name":"slug","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"itemId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"artifactId","in":"path"}],"responses":{"200":{"description":"URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DownloadUrl"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Page, item, or artifact not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Presign issuance rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/spaces":{"get":{"summary":"List Drive spaces the caller can access (personal + org shared)","responses":{"200":{"description":"Spaces","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpaceList"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create an org shared space","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSpaceRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Space"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/spaces/personal":{"post":{"summary":"Get-or-create the caller's personal space (idempotent, race-safe)","responses":{"200":{"description":"Space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Space"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Only session users have a personal space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/spaces/{id}/details":{"get":{"summary":"Space provenance — creator + recent activity (details/provenance)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpaceDetails"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/spaces/{id}":{"patch":{"summary":"Update a space (rename and/or change visibility)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSpaceRequest"}}}},"responses":{"200":{"description":"Renamed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Space"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/spaces/{id}/files/prepare":{"post":{"summary":"Prepare a Drive file upload (no-claim multipart; File attaches post-verify)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrepareFileRequest"}}}},"responses":{"200":{"description":"Session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrepareResponse"}}}},"400":{"description":"Bad request (e.g. invalid name/path)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Space not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Too many in-flight upload sessions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Size exceeds the maximum, or org storage quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Upload issuance rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/spaces/{id}/files":{"get":{"summary":"List files under a folder prefix (materialized-path listing)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"materialized folder path, e.g. /asset-packs/synty","example":"/"},"required":false,"description":"materialized folder path, e.g. /asset-packs/synty","name":"folder","in":"query"},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"recursive","in":"query"}],"responses":{"200":{"description":"Files","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileList"}}}},"400":{"description":"Bad path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Space not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/spaces/{id}/files/browse":{"get":{"summary":"Browse a folder: immediate subfolders + a cursor-paginated page of files (DEP-59)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"materialized folder path, e.g. /asset-packs/synty","example":"/"},"required":false,"description":"materialized folder path, e.g. /asset-packs/synty","name":"folder","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","exclusiveMinimum":0},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Folder page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FolderListing"}}}},"400":{"description":"Bad path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Space not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/spaces/{id}/files/search":{"get":{"summary":"Search files in a space (name + filters) with cursor pagination (DEP-59)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"q","in":"query"},{"schema":{"type":"string"},"required":false,"name":"ext","in":"query"},{"schema":{"type":["integer","null"],"minimum":0},"required":false,"name":"minSize","in":"query"},{"schema":{"type":["integer","null"],"minimum":0},"required":false,"name":"maxSize","in":"query"},{"schema":{"type":"string"},"required":false,"name":"after","in":"query"},{"schema":{"type":"string"},"required":false,"name":"before","in":"query"},{"schema":{"type":"string","enum":["staged","verified"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","enum":["active","inactive","none"]},"required":false,"name":"shared","in":"query"},{"schema":{"type":"string","description":"materialized folder path, e.g. /asset-packs/synty","example":"/"},"required":false,"description":"materialized folder path, e.g. /asset-packs/synty","name":"folder","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","exclusiveMinimum":0},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileSearchResult"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Space not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/spaces/{id}/files/{fileId}":{"patch":{"summary":"Rename and/or move a file (folder_path update)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"fileId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateFileRequest"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/File"}}}},"400":{"description":"Invalid name/path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a file (unreference; GC collects the blob past grace)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"fileId","in":"path"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/spaces/{id}/files/move-folder":{"post":{"summary":"Move a whole folder subtree (reparent every File under a prefix)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoveFolderRequest"}}}},"responses":{"200":{"description":"Moved count","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoveFolderResult"}}}},"400":{"description":"Invalid path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Space not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/spaces/{id}/files/{fileId}/details":{"get":{"summary":"Full power-user metadata for a file (sha256, refs, downloads) — DEP-50","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"fileId","in":"path"}],"responses":{"200":{"description":"Details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileDetails"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/spaces/{id}/files/{fileId}/download":{"get":{"summary":"Presigned GET for a file (egress recorded at issue time)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"fileId","in":"path"}],"responses":{"200":{"description":"URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DownloadUrl"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found or not yet verified","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Presign issuance rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects/{project}/share-links":{"post":{"summary":"Mint a share link over a project-side surface (project/channel/release/page)","parameters":[{"schema":{"type":"string","example":"cs3"},"required":true,"name":"project","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProjectShareLinkRequest"}}}},"responses":{"201":{"description":"Created — the only response that carries the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedShareLink"}}}},"400":{"description":"Bad request (missing subject for scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Project, channel, release, or page not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List share links over a project and its channels/releases/page","parameters":[{"schema":{"type":"string","example":"cs3"},"required":true,"name":"project","in":"path"}],"responses":{"200":{"description":"Links","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareLinkList"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/spaces/{id}/share-links":{"post":{"summary":"Mint a Drive share link (space/folder/file)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDriveShareLinkRequest"}}}},"responses":{"201":{"description":"Created — the only response that carries the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedShareLink"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Space or file not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List share links over a space","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Links","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareLinkList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Space not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/share-links":{"get":{"summary":"List every share link I or my org created, across ALL scopes (consolidated view)","parameters":[{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","exclusiveMinimum":0},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Links with resolved subject labels","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MyShareLinkList"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/share-links/{id}":{"delete":{"summary":"Revoke a share link (idempotent-ish; subsequent exercises 403)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects":{"get":{"summary":"List the projects in the caller's organization","responses":{"200":{"description":"Projects","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectList"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Share link, api key without project:read, or no active org","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a project (org owner/admin session, or an api key with project:create)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProjectRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"400":{"description":"Invalid slug or name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Requires an org owner/admin session or a project:create api key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Slug already exists in this org","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects/{project}":{"patch":{"summary":"Rename a project and/or change its visibility (owner/admin only)","parameters":[{"schema":{"type":"string","example":"cs3"},"required":true,"name":"project","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProjectRequest"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Requires an org owner/admin session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/users":{"get":{"summary":"List all users (site admin only), cursor-paginated newest-first","parameters":[{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","exclusiveMinimum":0},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Users","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminUserList"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Requires a site-admin session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a user (site admin only; optionally add to a chosen org)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUserRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminUser"}}}},"400":{"description":"Bad request (e.g. email already in use)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Requires a site-admin session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/users/{userId}":{"patch":{"summary":"Set a user's site role and/or disable them (site admin only)","parameters":[{"schema":{"type":"string"},"required":true,"name":"userId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUserRequest"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminUser"}}}},"400":{"description":"Bad request (e.g. cannot lock yourself out)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Requires a site-admin session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"User not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/members":{"get":{"summary":"List members of the caller's active org with their roles (owner/admin only)","responses":{"200":{"description":"Members","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgMemberList"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Requires an org owner/admin session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/orgs":{"get":{"summary":"List organizations the caller belongs to (with role + counts)","description":"A user session, or a PERSONAL api token (it lists its owner's memberships — the orgs it may select with x-depot-org). An org key is pinned to one org and gets 403.","responses":{"200":{"description":"Orgs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgList"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Requires a user session or a personal token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/orgs/{orgId}":{"get":{"summary":"Org overview — its projects and shared spaces (members only)","parameters":[{"schema":{"type":"string"},"required":true,"name":"orgId","in":"path"}],"responses":{"200":{"description":"Org","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgOverview"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Requires a user session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not a member / not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Rename an organization (owner/admin only; slug is immutable)","parameters":[{"schema":{"type":"string"},"required":true,"name":"orgId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenameOrgRequest"}}}},"responses":{"200":{"description":"Renamed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgOverview"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Requires an org owner/admin","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/orgs/{orgId}/members":{"get":{"summary":"List an org's members with roles (members only)","parameters":[{"schema":{"type":"string"},"required":true,"name":"orgId","in":"path"}],"responses":{"200":{"description":"Members","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgMemberList"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Requires a user session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not a member / not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Add an EXISTING user to the org by email (owner/admin only; no invites in v1)","parameters":[{"schema":{"type":"string"},"required":true,"name":"orgId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddMemberRequest"}}}},"responses":{"201":{"description":"Added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgMember"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Requires an org owner/admin","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Org or user not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Already a member","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/orgs/{orgId}/members/{userId}":{"patch":{"summary":"Set a member's role (owner/admin only; cannot demote the last owner)","parameters":[{"schema":{"type":"string"},"required":true,"name":"orgId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"userId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetMemberRoleRequest"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgMember"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Requires an org owner/admin","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Member not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Cannot demote the last owner","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Remove a member (owner/admin only; cannot remove the last owner)","parameters":[{"schema":{"type":"string"},"required":true,"name":"orgId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"userId","in":"path"}],"responses":{"200":{"description":"Removed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Requires an org owner/admin","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Member not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Cannot remove the last owner","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/orgs/{orgId}/api-keys":{"get":{"summary":"List an org's API keys (owner/admin only; never returns secrets)","parameters":[{"schema":{"type":"string"},"required":true,"name":"orgId","in":"path"}],"responses":{"200":{"description":"Keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyList"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Requires an org owner/admin","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not a member / not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Mint an org-scoped API key (owner/admin only; secret returned once)","parameters":[{"schema":{"type":"string"},"required":true,"name":"orgId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyRequest"}}}},"responses":{"201":{"description":"Created — secret in `key`, shown once","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedApiKey"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Requires an org owner/admin","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not a member / not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/orgs/{orgId}/api-keys/{keyId}":{"delete":{"summary":"Revoke (delete) an org API key (owner/admin only)","parameters":[{"schema":{"type":"string"},"required":true,"name":"orgId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"keyId","in":"path"}],"responses":{"200":{"description":"Revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Requires an org owner/admin","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Key not found in this org","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/orgs/{orgId}/audit":{"get":{"summary":"The org's audit log — filtered, keyset-paginated (owner/admin only)","parameters":[{"schema":{"type":"string"},"required":true,"name":"orgId","in":"path"},{"schema":{"type":"string","enum":["user","api_key","share_link","system"]},"required":false,"name":"actorType","in":"query"},{"schema":{"type":"string"},"required":false,"name":"actorId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"actionPrefix","in":"query"},{"schema":{"type":"string"},"required":false,"name":"subjectType","in":"query"},{"schema":{"type":"string","description":"ISO-8601 lower bound"},"required":false,"description":"ISO-8601 lower bound","name":"from","in":"query"},{"schema":{"type":"string","description":"ISO-8601 upper bound"},"required":false,"description":"ISO-8601 upper bound","name":"to","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","exclusiveMinimum":0},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditPage"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Requires an org owner/admin","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not a member / not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/security":{"get":{"summary":"Login/logout auth events across the site (site admin only)","parameters":[{"schema":{"type":"string","enum":["user","api_key","share_link","system"]},"required":false,"name":"actorType","in":"query"},{"schema":{"type":"string"},"required":false,"name":"actorId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"actionPrefix","in":"query"},{"schema":{"type":"string"},"required":false,"name":"subjectType","in":"query"},{"schema":{"type":"string","description":"ISO-8601 lower bound"},"required":false,"description":"ISO-8601 lower bound","name":"from","in":"query"},{"schema":{"type":"string","description":"ISO-8601 upper bound"},"required":false,"description":"ISO-8601 upper bound","name":"to","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","exclusiveMinimum":0},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditPage"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Requires a site-admin session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me":{"get":{"summary":"The caller's resolved identity (any authenticated actor)","responses":{"200":{"description":"Identity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Dead share token, or an api key without project:read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/audit":{"get":{"summary":"The caller's account activity (auth + personal tokens), keyset-paginated","parameters":[{"schema":{"type":"string","enum":["user","api_key","share_link","system"]},"required":false,"name":"actorType","in":"query"},{"schema":{"type":"string"},"required":false,"name":"actorId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"actionPrefix","in":"query"},{"schema":{"type":"string"},"required":false,"name":"subjectType","in":"query"},{"schema":{"type":"string","description":"ISO-8601 lower bound"},"required":false,"description":"ISO-8601 lower bound","name":"from","in":"query"},{"schema":{"type":"string","description":"ISO-8601 upper bound"},"required":false,"description":"ISO-8601 upper bound","name":"to","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","exclusiveMinimum":0},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditPage"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Requires a user session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/sessions":{"get":{"summary":"The caller's ACTIVE (non-expired) sessions, current one flagged","responses":{"200":{"description":"Sessions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionList"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Requires a user session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/sessions/{id}":{"delete":{"summary":"Revoke one of the caller's sessions (cannot be a share-link/api-key actor)","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Requires a user session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Session not found for this user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/sessions/revoke-others":{"post":{"summary":"Revoke all of the caller's sessions except the current one","responses":{"200":{"description":"Count revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeOthersResult"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Requires a user session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/api-keys":{"post":{"summary":"Mint a PERSONAL API token (session only; secret returned once)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePersonalApiKeyRequest"}}}},"responses":{"201":{"description":"Created — secret in `key`, shown once","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedApiKey"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Requires a user session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List the caller's PERSONAL API tokens (session only; never returns secrets)","responses":{"200":{"description":"Keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyList"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Requires a user session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/api-keys/{keyId}":{"delete":{"summary":"Revoke one of the caller's PERSONAL API tokens (session only)","parameters":[{"schema":{"type":"string"},"required":true,"name":"keyId","in":"path"}],"responses":{"200":{"description":"Revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Requires a user session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Token not found for this user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/search":{"get":{"summary":"Unified command-palette search across orgs/projects/spaces/folders/files","parameters":[{"schema":{"type":"string"},"required":false,"name":"q","in":"query"},{"schema":{"type":"integer","exclusiveMinimum":0,"description":"per-group cap"},"required":false,"description":"per-group cap","name":"limit","in":"query"}],"responses":{"200":{"description":"Grouped, access-scoped results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResults"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{}}