REST API reference.

GET /healthz

Liveness (the process answers) Internal: infrastructure endpoint, not wrapped by the SDKs.

Operation: getHealthz · Auth: none

Responses: 200 Alive (Healthz)

GET /readyz

Readiness (db, ingest bucket, content bucket) Internal: infrastructure endpoint, not wrapped by the SDKs.

Operation: getReadyz · Auth: none

Responses: 200 Ready (Readyz), 503 A dependency failed; the body has the same shape with ready false. (Readyz)

POST /v1/internal/storage-events

B2 event notifications (ObjectCreated completes the matching upload). Body limit 1 MiB. Internal: infrastructure endpoint, not wrapped by the SDKs.

Operation: postStorageEvents · Auth: StorageEventSignature

Body (application/json, StorageEvents, required)

Responses: 200 Counted (StorageEventsResult), 400 BadRequest, 401 Unauthorized, 413 PayloadTooLarge, 500 Internal

GET /v1/me

The session's user, organization, role and staff flag

Operation: getMe · Auth: BrowserSession + WorkosUserId

Responses: 200 The caller (Me), 401 Unauthorized, 403 Forbidden, 404 NotFound, 429 TooManyRequests, 503 Unavailable

GET /v1/organizations

Only the caller's organization (next_cursor is always null)

Operation: listOrganizations · Auth: BrowserSession + WorkosUserId

Responses: 200 One page (OrganizationList), 401 Unauthorized, 403 Forbidden, 429 TooManyRequests, 503 Unavailable

POST /v1/organizations

Staff create an organization (201); a tenant gets its own provisioned organization back (200, body ignored)

Operation: createOrganization · Auth: BrowserSession + WorkosUserId + RequestSignature

Body (application/json, OrganizationCreate, optional)

Responses: 200 Tenant caller: its own organization (Organization), 201 Staff caller: the new organization (Organization), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

GET /v1/projects

Projects of the caller's organization, keyset, newest first

Operation: listProjects · Auth: BrowserSession + WorkosUserId

Responses: 200 One page (ProjectList), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 429 TooManyRequests, 503 Unavailable

POST /v1/projects

Create a project and its first signing key (body limit 256 KiB)

Operation: createProject · Auth: BrowserSession + WorkosUserId + RequestSignature

Body (application/json, ProjectCreate, required)

Responses: 201 Created (Project), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 409 Conflict, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

GET /v1/projects/{slug}

Operation: getProject · Auth: BrowserSession + WorkosUserId or ApiKey (files:read) or ApiKeyHeader (files:read)

Responses: 200 The project (Project), 401 Unauthorized, 403 Forbidden, 404 NotFound, 429 TooManyRequests, 503 Unavailable

PATCH /v1/projects/{slug}

Owner settings; storage_hard_limit_bytes and pricing_multiplier are staff-only (403 staff_only_field); custom_domains is refused (400, details.hint staff route). Body limit 256 KiB.

Operation: updateProject · Auth: BrowserSession + WorkosUserId + RequestSignature

Body (application/json, ProjectPatch, required)

Responses: 200 The updated project; callback_secret is present once when a secret was generated or rotated (Project), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

DELETE /v1/projects/{slug}

Suspends the project (suspended_by owner). There is no hard delete.

Operation: suspendProject · Auth: BrowserSession + WorkosUserId + RequestSignature

Responses: 204 Suspended (repeat calls too), 401 Unauthorized, 403 Forbidden, 404 NotFound, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

GET /v1/key

The calling API key (SDKs resolve their project from it); Cache-Control no-store

Operation: getKey · Auth: ApiKey or ApiKeyHeader

Responses: 200 The key (KeyIntrospection), 401 Unauthorized, 403 Forbidden, 429 TooManyRequests

GET /v1/projects/{slug}/keys

Every key of the project, newest first (bounded, next_cursor null)

Operation: listApiKeys · Auth: BrowserSession + WorkosUserId

Responses: 200 The keys (ApiKeyList), 401 Unauthorized, 403 Forbidden, 404 NotFound, 429 TooManyRequests, 503 Unavailable

POST /v1/projects/{slug}/keys

New key; plaintext_secret is returned only here. Omitted scopes = full project access.

Operation: createApiKey · Auth: BrowserSession + WorkosUserId + RequestSignature

Body (application/json, ApiKeyCreate, required)

Responses: 201 Created (ApiKeyCreated), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 409 Conflict, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

POST /v1/projects/{slug}/keys/{keyId}/revoke

Operation: revokeApiKey · Auth: BrowserSession + WorkosUserId + RequestSignature

Responses: 200 The key, now revoked (idempotent) (ApiKeyEnvelope), 401 Unauthorized, 403 Forbidden, 404 NotFound, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

POST /v1/projects/{slug}/keys/{keyId}/rotate

New key with the same name and scopes; the old one is revoked in the same transaction

Operation: rotateApiKey · Auth: BrowserSession + WorkosUserId + RequestSignature

Responses: 200 The new key (ApiKeyRotated), 401 Unauthorized, 403 Forbidden, 404 NotFound, 409 Conflict, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

GET /v1/projects/{slug}/signing-keys

kid, status and retire_after of every signing key (never secrets)

Operation: listSigningKeys · Auth: BrowserSession + WorkosUserId

Responses: 200 The signing keys (SigningKeyList), 401 Unauthorized, 403 Forbidden, 404 NotFound, 429 TooManyRequests, 503 Unavailable

POST /v1/projects/{slug}/signing-keys/rotate

New active kid; the previous one keeps verifying for 24 h

Operation: rotateSigningKey · Auth: BrowserSession + WorkosUserId + RequestSignature

Responses: 200 Rotated (SigningKeyRotation), 401 Unauthorized, 403 Forbidden, 404 NotFound, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

POST /v1/projects/{slug}/signed-url

Signed delivery URL for a ready file (own rate limit, 60/min/project; audited)

Operation: createSignedUrl · Auth: BrowserSession + WorkosUserId + RequestSignature or ApiKey (urls:sign) or ApiKeyHeader (urls:sign)

Body (application/json, SignedUrlRequest, required)

Responses: 200 The URL (SignedUrl), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 409 Conflict, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

GET /v1/projects/{slug}/watermark-presets

Every preset of the project (bounded; no next_cursor)

Operation: listWatermarkPresets · Auth: BrowserSession + WorkosUserId or ApiKey (files:read) or ApiKeyHeader (files:read)

Responses: 200 The presets (WatermarkPresetList), 401 Unauthorized, 403 Forbidden, 404 NotFound, 429 TooManyRequests, 503 Unavailable

PUT /v1/projects/{slug}/watermark-presets

Creates a new preset on every call (not idempotent). The image is one of the project's ready files.

Operation: createWatermarkPreset · Auth: BrowserSession + WorkosUserId + RequestSignature or ApiKey (files:write) or ApiKeyHeader (files:write)

Body (application/json, WatermarkPresetInput, required)

Responses: 201 Created (WatermarkPreset), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 409 Conflict, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

GET /v1/projects/{slug}/watermark-presets/{id}

Operation: getWatermarkPreset · Auth: BrowserSession + WorkosUserId or ApiKey (files:read) or ApiKeyHeader (files:read)

Responses: 200 The preset (WatermarkPreset), 401 Unauthorized, 403 Forbidden, 404 NotFound, 429 TooManyRequests, 503 Unavailable

PUT /v1/projects/{slug}/watermark-presets/{id}

Creates (201) or replaces (200) the preset with this id

Operation: saveWatermarkPreset · Auth: BrowserSession + WorkosUserId + RequestSignature or ApiKey (files:write) or ApiKeyHeader (files:write)

Body (application/json, WatermarkPresetInput, required)

Responses: 200 Replaced (WatermarkPreset), 201 Created (WatermarkPreset), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 409 Conflict, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

DELETE /v1/projects/{slug}/watermark-presets/{id}

An unknown id is 404; the project default is 409 default_watermark_in_use

Operation: deleteWatermarkPreset · Auth: BrowserSession + WorkosUserId + RequestSignature or ApiKey (files:write) or ApiKeyHeader (files:write)

Responses: 204 Deleted, 401 Unauthorized, 403 Forbidden, 404 NotFound, 409 Conflict, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

GET /v1/projects/{slug}/recipes

Every recipe of the project (bounded, next_cursor null)

Operation: listRecipes · Auth: BrowserSession + WorkosUserId or ApiKey (recipes:read) or ApiKeyHeader (recipes:read)

Responses: 200 The recipes (RecipeList), 401 Unauthorized, 403 Forbidden, 404 NotFound, 429 TooManyRequests, 503 Unavailable

PUT /v1/projects/{slug}/recipes

Creates a new recipe on every call (not idempotent)

Operation: createRecipe · Auth: BrowserSession + WorkosUserId + RequestSignature or ApiKey (recipes:write) or ApiKeyHeader (recipes:write)

Body (application/json, RecipeInput, required)

Responses: 201 Created (Recipe), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 409 Conflict, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

GET /v1/projects/{slug}/recipes/{id}

Operation: getRecipe · Auth: BrowserSession + WorkosUserId or ApiKey (recipes:read) or ApiKeyHeader (recipes:read)

Responses: 200 The recipe (Recipe), 401 Unauthorized, 403 Forbidden, 404 NotFound, 429 TooManyRequests, 503 Unavailable

PUT /v1/projects/{slug}/recipes/{id}

Creates (201) or replaces (200) the recipe with this id

Operation: saveRecipe · Auth: BrowserSession + WorkosUserId + RequestSignature or ApiKey (recipes:write) or ApiKeyHeader (recipes:write)

Body (application/json, RecipeInput, required)

Responses: 200 Replaced (Recipe), 201 Created (Recipe), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 409 Conflict, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

DELETE /v1/projects/{slug}/recipes/{id}

Idempotent: an unknown id is 204 too

Operation: deleteRecipe · Auth: BrowserSession + WorkosUserId + RequestSignature or ApiKey (recipes:write) or ApiKeyHeader (recipes:write)

Responses: 204 Deleted, 401 Unauthorized, 403 Forbidden, 404 NotFound, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

GET /v1/projects/{slug}/files

Keyset, newest first; no status filter = every file that is not deleted. library, folder, search, has_location, bbox or a sort other than uploaded on a project with more files rows (any status) than MEDIA_LIBRARY_MAX_UNINDEXED_FILES (default 100000; 0 = no limit) is 422 filter_unavailable until the library indexes are built (phase 1b; the gate lifts on its own once they are, within 5 min); search ('search is not available on projects this large') and status=deleted with any of those ('listing deleted files with library filters is not available on projects this large') stay size-gated after that (no index serves them). Checked after query validation and library resolution (malformed input is still 400, an unknown library 404); status, q and the plain listing always work. q must not contain U+0000 (400 invalid_request).

Operation: listFiles · Auth: BrowserSession + WorkosUserId or ApiKey (files:read) or ApiKeyHeader (files:read)

Responses: 200 One page (FileList), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 422 Unprocessable, 429 TooManyRequests, 503 Unavailable

GET /v1/projects/{slug}/files/{fileSlug}

A deleted file is 404 file_not_found

Operation: getFile · Auth: BrowserSession + WorkosUserId or ApiKey (files:read) or ApiKeyHeader (files:read)

Responses: 200 The file (File), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 429 TooManyRequests, 503 Unavailable

PATCH /v1/projects/{slug}/files/{fileSlug}

Title, alt text, folder, library. folder/library need MEDIA_LIBRARY_WRITES (409 media_library_disabled); title/alt_text always work. A folder or library change is also 422 filter_unavailable on a project over MEDIA_LIBRARY_MAX_UNINDEXED_FILES files rows (any status) until the library indexes are built (phase 1b), checked after body validation and library resolution. A library change without folder puts the file at the target's root; it purges nothing in phase 1 (every library is inherit). A deleted file is 404 file_not_found. Audit file.update when something changed.

Operation: updateFile · Auth: BrowserSession + WorkosUserId + RequestSignature or ApiKey (files:write) or ApiKeyHeader (files:write)

Body (application/json, FilePatch, required)

Responses: 200 The file (without location) (File), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 409 Conflict, 413 PayloadTooLarge, 422 Unprocessable, 429 TooManyRequests, 503 Unavailable

DELETE /v1/projects/{slug}/files/{fileSlug}

status deleted + purge; repeat deletes are 204; the object is left for gc

Operation: deleteFile · Auth: BrowserSession + WorkosUserId + RequestSignature or ApiKey (files:write) or ApiKeyHeader (files:write)

Responses: 204 Deleted, 401 Unauthorized, 403 Forbidden, 404 NotFound, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

POST /v1/projects/{slug}/files/{fileSlug}/moderation-notes

One note per (project, file slug); a second replaces it

Operation: createModerationNote · Auth: BrowserSession + WorkosUserId + RequestSignature

Body (application/json, ModerationNoteInput, required)

Responses: 201 The note (ModerationNote), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

POST /v1/projects/{slug}/files/move

Bulk move (1..1000 slugs, one transaction) into one folder, and into one library when given (omitted = each file keeps its library). Needs MEDIA_LIBRARY_WRITES. On a project with more files rows (any status) than MEDIA_LIBRARY_MAX_UNINDEXED_FILES (default 100000; 0 = no limit) this is 422 filter_unavailable until the library indexes are built (phase 1b), checked after body validation and library resolution. Slugs with no live file (or that are not valid slugs) are listed in not_found. No purge and no webhook in phase 1 (slugs and URLs do not change; the response lists the moved files; control-plane.md). Audit file.move with counts. Body up to 256 KiB.

Operation: moveFiles · Auth: BrowserSession + WorkosUserId + RequestSignature or ApiKey (files:write) or ApiKeyHeader (files:write)

Body (application/json, FileMove, required)

Responses: 200 Where every requested slug ended up (FileMoveResult), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 409 Conflict, 413 PayloadTooLarge, 422 Unprocessable, 429 TooManyRequests, 503 Unavailable

GET /v1/projects/{slug}/libraries

Live named libraries, keyset, newest first; the built-in default library is not listed

Operation: listLibraries · Auth: BrowserSession + WorkosUserId or ApiKey (files:read) or ApiKeyHeader (files:read)

Responses: 200 One page (LibraryList), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 429 TooManyRequests, 503 Unavailable

POST /v1/projects/{slug}/libraries

Needs MEDIA_LIBRARY_WRITES (409 media_library_disabled). slug is trimmed and lowercased (400 invalid_library_slug; default is reserved); a live library already using it is 409 library_slug_taken (a deleted library's slug is reusable). On a project with more files rows (any status) than MEDIA_LIBRARY_MAX_UNINDEXED_FILES (default 100000; 0 = no limit) this is 422 filter_unavailable until the library indexes are built (phase 1b), checked after body validation. Audit library.create.

Operation: createLibrary · Auth: BrowserSession + WorkosUserId + RequestSignature or ApiKey (files:write) or ApiKeyHeader (files:write)

Body (application/json, LibraryCreate, required)

Responses: 201 The library (Library), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 409 Conflict, 413 PayloadTooLarge, 422 Unprocessable, 429 TooManyRequests, 503 Unavailable

GET /v1/projects/{slug}/libraries/{lib}

default answers the synthetic default library (library_id null); an unknown or deleted slug is 404 library_not_found

Operation: getLibrary · Auth: BrowserSession + WorkosUserId or ApiKey (files:read) or ApiKeyHeader (files:read)

Responses: 200 The library (Library), 401 Unauthorized, 403 Forbidden, 404 NotFound, 429 TooManyRequests, 503 Unavailable

PATCH /v1/projects/{slug}/libraries/{lib}

Needs MEDIA_LIBRARY_WRITES. delivery_access and map_enabled are 400 not_supported in phase 1. default accepts only allowed_origins, stored as the project-wide library origins (they admit an embedding origin on every library of the project); anything else on default is 400 default_library_immutable. Audit library.update when a field was given.

Operation: updateLibrary · Auth: BrowserSession + WorkosUserId + RequestSignature or ApiKey (files:write) or ApiKeyHeader (files:write)

Body (application/json, LibraryPatch, required)

Responses: 200 The library (Library), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 409 Conflict, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

DELETE /v1/projects/{slug}/libraries/{lib}

Needs MEDIA_LIBRARY_WRITES. Soft delete; 409 library_not_empty while it holds ready or blocked files or created/uploaded/processing uploads; default is 400 default_library_immutable. On a project with more files rows (any status) than MEDIA_LIBRARY_MAX_UNINDEXED_FILES (default 100000; 0 = no limit) this is 422 filter_unavailable until the library indexes are built (phase 1b; before that the emptiness check scans the project), checked after the library resolved (400/404 first). Audit library.delete.

Operation: deleteLibrary · Auth: BrowserSession + WorkosUserId + RequestSignature or ApiKey (files:write) or ApiKeyHeader (files:write)

Responses: 204 Deleted, 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 409 Conflict, 413 PayloadTooLarge, 422 Unprocessable, 429 TooManyRequests, 503 Unavailable

POST /v1/projects/{slug}/library-sessions

Mint a short-lived ls1 library session for one end user (subject) and one embedding origin, plus the signed embed_url of the picker. API keys only (scope library:sessions; browse/browse_own also need files:read, upload files:write, and a protected scope urls:sign: else 403 scope_missing). 409 library_sessions_disabled while LIBRARY_SESSIONS is off; 409 subject_key_unavailable without SUBJECT_KEY_SECRET. origin must be listed in the library's allowed_origins or the project-wide ones (PATCH …/libraries/default), else 403 origin_not_allowed. browse and browse_own together are 400 invalid_permissions. refresh_of: a live (not revoked) token of the same project, library, origin and subject (≤ 10 min past its exp) keeps its sid; one that differs or widens is 400 refresh_mismatch; an unverifiable or revoked one starts a new session. Within a revocation cutoff (now ≤ the project's or library's sessions_not_before) mint is 409 sessions_recently_revoked (Retry-After). A key with no scopes (legacy, all scopes) may mint. No SQL write per mint; a per-pod limiter answers 429.

Operation: createLibrarySession · Auth: ApiKey (library:sessions) or ApiKeyHeader (library:sessions)

Body (application/json, LibrarySessionCreate, required)

Responses: 201 The session (LibrarySessionCreated), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 409 Conflict, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

GET /v1/library/files

The session's visible set: ready files of the token's library and folder subtree, newest first; with browse_own only the files whose current revision this subject uploaded (size-gated with 422 filter_unavailable until the uploader indexes exist). 403 permission_denied without browse/browse_own. Thumbnails: unsigned for a public scope whose project allowlists the thumbnail chain, else signed with the project's active key (hourly, shared per project; no /signed-url budget). An ls1 token is the only credential; 401 session_expired, session_revoked, minting_key_revoked or invalid_session ends it.

Operation: listLibrarySessionFiles · Auth: LibrarySession

Responses: 200 One page (LibraryFileList), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 409 Conflict, 422 Unprocessable, 429 TooManyRequests, 503 Unavailable

POST /v1/library/uploads

Upload into the session's library and folder (permission upload; MEDIA_LIBRARY_WRITES). The file slug is always generated (a session never overwrites a file); the subject comes from the token (files.uploader_key at publish). Proxy mode only: PUT the bytes to put_url (≤ min(15 min, token exp)). size_bytes over the session's max_file_bytes is 413 file_too_large; more than max_uploads uploads in one picker session is 429 session_upload_limit (per pod).

Operation: createLibrarySessionUpload · Auth: LibrarySession

Body (application/json, LibraryUploadCreate, required)

Responses: 201 The upload and its PUT URL (LibraryUploadCreated), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 409 Conflict, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

GET /v1/library/uploads/{id}

An upload of THIS picker session (its sid, kept across refresh_of); anything else is 404 upload_not_found. file is set once the upload is ready and the file is still that upload's revision inside the session's scope.

Operation: getLibrarySessionUpload · Auth: LibrarySession

Responses: 200 The upload (LibraryUpload), 401 Unauthorized, 403 Forbidden, 404 NotFound, 409 Conflict, 429 TooManyRequests, 503 Unavailable

POST /v1/library/uploads/{id}/complete

Idempotent fallback (the proxy PUT already completes the upload): completes a created upload whose bytes are stored (409 ingest_object_missing otherwise). Own picker session only.

Operation: completeLibrarySessionUpload · Auth: LibrarySession

Responses: 200 The upload (LibraryUpload), 401 Unauthorized, 403 Forbidden, 404 NotFound, 409 Conflict, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

GET /embed/{project}/{library}

The picker page (open embed_url in an iframe; protocol img2site.library.v1 in contracts/v2/sdk-and-apps.md). Checked locally against EMBED_URL_SECRET, no database lookup. 200 carries Content-Security-Policy with frame-ancestors <o>, script-src/style-src 'self', no inline code, Referrer-Policy no-referrer and Cache-Control no-store. Refusals carry frame-ancestors 'none': 400 invalid_origin, 403 invalid_embed_url or embed_url_expired, 404 while LIBRARY_SESSIONS is off.

Operation: getLibraryEmbed · Auth: EmbedUrlSignature

Responses: 200 The picker page, 400 BadRequest, 403 Forbidden, 404 NotFound

GET /embed/_assets/{file}

The picker's script and stylesheet (fixed names, Cache-Control public, max-age=300). 404 for any other name or while LIBRARY_SESSIONS is off; 503 embed_unavailable when the image was built without them.

Operation: getLibraryEmbedAsset · Auth: none

Responses: 200 The asset, 404 NotFound, 503 Unavailable

GET /v1/projects/{slug}/uploads

Upload sessions, keyset, newest first

Operation: listUploads · Auth: BrowserSession + WorkosUserId or ApiKey (files:read) or ApiKeyHeader (files:read)

Responses: 200 One page (UploadSessionList), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 429 TooManyRequests, 503 Unavailable

POST /v1/projects/{slug}/uploads

Create an upload session (upload-flow.md). Exactly one of direct, multipart, proxy is present. A single-part session (direct PUT or proxy) lives 15 min; a multipart session (parts > 1) lives 12 h (expires_at) while its part URLs last 15 min (multipart.urls_expire_at), re-signed by POST …/parts. size_bytes above INGEST_MAX_BYTES is 413 file_too_large; with mode proxy, above PROXY_MAX_BYTES (default 100000000, Cloudflare's request body limit) it is 413 proxy_upload_too_large (use direct; multipart for files above 100 MB). library/folder need MEDIA_LIBRARY_WRITES (409 media_library_disabled); an unknown or deleted library is 404 library_not_found.

Operation: createUpload · Auth: BrowserSession + WorkosUserId + RequestSignature or ApiKey (files:write) or ApiKeyHeader (files:write)

Body (application/json, UploadCreate, required)

Responses: 201 The session and where to put the bytes (UploadCreated), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 409 Conflict, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

GET /v1/projects/{slug}/uploads/{id}

Operation: getUpload · Auth: BrowserSession + WorkosUserId or ApiKey (files:read) or ApiKeyHeader (files:read)

Responses: 200 The session (UploadSession), 401 Unauthorized, 403 Forbidden, 404 NotFound, 429 TooManyRequests, 503 Unavailable

DELETE /v1/projects/{slug}/uploads/{id}

Abort a session the client gave up on (upload-flow.md, Aborting an upload). created becomes expired with error_code upload_aborted, then a multipart upload is aborted in storage (best effort; a refusal is logged and the bucket lifecycle is the backstop). Idempotent: an expired session (aborted or expired by the reconciler) answers 204 again and retries the multipart abort. Any later status is 409 upload_not_pending (details.status). On a suspended project it works for browser sessions only (API keys of a suspended project do not authenticate). Losing the race with a complete that already moved the session to uploaded is 409, and the file may still become ready. Same auth as complete, exempt from the project write limit. Frees the session at once for library deletion, which a pending session blocks until it expires (12 h for multipart).

Operation: abortUpload · Auth: BrowserSession + WorkosUserId + RequestSignature or ApiKey (files:write) or ApiKeyHeader (files:write)

Responses: 204 Aborted (or already expired), 401 Unauthorized, 403 Forbidden, 404 NotFound, 409 Conflict, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

POST /v1/projects/{slug}/uploads/{id}/complete

Optional accelerator; completes an S3 multipart first. Body optional except for multipart (limit 1 MiB); a multipart session without parts completes only when its object is already assembled at exactly size_bytes (an api crash after CompleteMultipartUpload), else 400 parts_required: parts must be exactly 1..N with non-blank etags, all uploaded (read-only part listing), every part but the last at least 5 MiB, adding up to size_bytes, else 400 invalid_parts and the multipart upload stays intact and completable. A part listing the backend refuses is 503 storage_unavailable. A multipart session at or past its expires_at is 410 upload_expired (nothing is assembled; start a new upload), except without parts when its object was already assembled at exactly size_bytes, which still completes.

Operation: completeUpload · Auth: BrowserSession + WorkosUserId + RequestSignature or ApiKey (files:write) or ApiKeyHeader (files:write)

Body (application/json, UploadComplete, optional)

Responses: 200 Already past created: the session unchanged (UploadSession), 202 Transitioned to uploaded; processing is queued (UploadSession), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 409 Conflict, 410 Gone, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

POST /v1/projects/{slug}/uploads/{id}/parts

Resume a multipart session (upload-flow.md, Resuming a multipart upload): the parts storage already holds (part_number, size, etag) and freshly signed URLs for part_numbers, by default every part not uploaded yet (lowest first, at most 1000). Read-only: expires_at does not move; each URL lasts min(15 min, until expires_at) and signs its part's exact Content-Length. Same auth and body limit (64 KiB) as create, exempt from the project write limit like create and complete. Checked in this order: 404 upload_not_found, 403 project_suspended, the body (400 invalid_json, then 400 invalid_request for the schema: unknown keys, not an array, 0 or more than 1000 entries, a number outside 1..10000), 400 not_multipart, 410 upload_expired / 409 upload_not_pending by status, 409 upload_not_resumable, 410 upload_expired by expires_at, then 400 invalid_parts (above part_count, then repeats), then the listing (503), and 410 again when less than ~2 s are left to sign. 400 not_multipart for a single-part session, 400 invalid_parts for part numbers above part_count or repeated; 409 upload_not_pending past created (or when the multipart upload is no longer open), 409 upload_not_resumable for a multipart session created before part refresh existed; 410 upload_expired at or after expires_at; 503 storage_unavailable when storage refuses the part listing.

Operation: refreshUploadParts · Auth: BrowserSession + WorkosUserId + RequestSignature or ApiKey (files:write) or ApiKeyHeader (files:write)

Body (application/json, UploadPartsRequest, optional)

Responses: 200 Uploaded parts and fresh part URLs (UploadParts), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 409 Conflict, 410 Gone, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

PUT /v1/uploads/{id}/bytes

Proxy mode: the signed URL from proxy.put_url is the credential; PUT it as returned (its origin is PUBLIC_UPLOAD_ORIGIN, deployment-defined; today the api origin). Content-Length must equal size_bytes and Content-Type the session's. The only CORS route: OPTIONS answers 204 for any origin (Allow-Methods PUT, Allow-Headers content-type, Max-Age 600, no credentials) and every PUT response, errors included, carries Access-Control-Allow-Origin *. 401 is invalid_signature or signature_expired.

Operation: putUploadBytes · Auth: UploadUrlSignature

Body (image/*, required)

Responses: 204 Stored and completed, 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 409 Conflict, 411 LengthRequired, 413 PayloadTooLarge, 415 UnsupportedMediaType, 422 Unprocessable, 503 Unavailable

GET /v1/projects/{slug}/usage

Storage (live), hourly and daily metering rows; default range the last 30 days, capped at 90

Operation: getUsage · Auth: BrowserSession + WorkosUserId or ApiKey (files:read) or ApiKeyHeader (files:read)

Responses: 200 Usage (Usage), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 429 TooManyRequests, 503 Unavailable

GET /v1/admin/audit-log

The caller's organization, newest first; staff actors are hidden

Operation: listAuditLog · Auth: BrowserSession + WorkosUserId

Responses: 200 One page (AuditList), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 429 TooManyRequests, 503 Unavailable

GET /v1/billing/summary

Operation: getBillingSummary · Auth: BrowserSession + WorkosUserId

Responses: 200 The caller's organization billing state (BillingSummary), 401 Unauthorized, 403 Forbidden, 404 NotFound, 429 TooManyRequests, 503 Unavailable

GET /v1/billing/invoices

Stripe invoices of the organization (empty without a Stripe customer; always empty for a Creem organization, whose receipts Creem emails and shows in its portal)

Operation: listInvoices · Auth: BrowserSession + WorkosUserId

Responses: 200 Invoices (InvoiceList), 401 Unauthorized, 403 Forbidden, 404 NotFound, 429 TooManyRequests, 503 Unavailable

POST /v1/billing/checkout-session

Checkout for a published plan with the summary's checkout_provider (Stripe Checkout, or Creem when enabled for the organization); redirects must be on DASHBOARD_ORIGIN; 409 already_subscribed; 503 billing_price_mismatch, stripe_request_failed, creem_request_failed

Operation: createCheckoutSession · Auth: BrowserSession + WorkosUserId + RequestSignature

Body (application/json, CheckoutRequest, required)

Responses: 200 The Checkout session (StripeSession), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 409 Conflict, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

POST /v1/billing/portal-session

Billing portal: Creem's customer portal for a Creem organization (id null), else Stripe's (creates the Stripe customer on first use); body optional

Operation: createPortalSession · Auth: BrowserSession + WorkosUserId + RequestSignature

Body (application/json, PortalRequest, optional)

Responses: 200 The portal session (PortalSession), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

POST /v1/billing/webhook

Stripe events (idempotent on the event id). Body limit 1 MiB. A database failure is 500 so Stripe retries. Internal: infrastructure endpoint, not wrapped by the SDKs.

Operation: postStripeWebhook · Auth: StripeSignature

Body (application/json, StripeEvent, required)

Responses: 200 Processed, duplicate or ignored (StripeWebhookResult), 400 BadRequest, 401 Unauthorized, 409 Conflict, 413 PayloadTooLarge, 500 Internal, 503 Unavailable

POST /v1/billing/cancel-subscription

Creem organizations only: cancel at the end of the paid period (no further charges; the plan stays active until then). 409 use_billing_portal (Stripe organization), no_subscription, already_cancelling; 503 billing_unavailable, creem_request_failed. Body optional: none or an empty JSON object (any field is 400 invalid_request).

Operation: cancelSubscription · Auth: BrowserSession + WorkosUserId + RequestSignature

Body (application/json, CancelSubscriptionRequest, optional)

Responses: 200 The cancellation was accepted; status is the status the api recorded (scheduled_cancel, or canceled/expired when the subscription has ended) (CancelSubscriptionResult), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 409 Conflict, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

POST /v1/billing/creem/webhook

Creem events (idempotent on the event id; credits only from subscription.paid). Body limit 1 MiB. 400 invalid_json, invalid_request (including a created_at not in epoch milliseconds), creem_mode_mismatch; 401 invalid_signature; 503 billing_unavailable, billing_customer_unmapped (no organization, or no metadata.organization_id and the subscription/customer maps to more than one), billing_plan_unmapped (subscription.paid for a product outside the configured CREEM_*_PRODUCT_ID), billing_subscription_mismatch, billing_grant_not_found, creem_request_failed: the event is not recorded, so Creem retries. In test mode an event of an organization outside CREEM_ALLOWED_ORGANIZATION_IDS is recorded and ignored (200). Internal: infrastructure endpoint, not wrapped by the SDKs.

Operation: postCreemWebhook · Auth: CreemSignature

Body (application/json, CreemEvent, required)

Responses: 200 Processed, duplicate or ignored (CreemWebhookResult), 400 BadRequest, 401 Unauthorized, 413 PayloadTooLarge, 500 Internal, 503 Unavailable

POST /v1/public/access-requests

Marketing intake: 10/min per IP, 3/h per email. CORS for img2.site and localhost.

Operation: createAccessRequest · Auth: none

Body (application/json, AccessRequestInput, required)

Responses: 202 Accepted (AccessRequestAccepted), 400 BadRequest, 413 PayloadTooLarge, 429 TooManyRequests

GET /v1/public/status

Last 24 h of status samples per service plus open and recent incidents (Cache-Control public, max-age=30)

Operation: getPublicStatus · Auth: none

Responses: 200 Status (PublicStatus)

GET /v1/staff/access-requests

Operation: staffListAccessRequests · Auth: Staff + WorkosUserId

Responses: 200 One page (StaffAccessRequestList), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 429 TooManyRequests, 503 Unavailable

GET /v1/staff/organizations/{organization_id}

One organization with its quota state; audited as staff.organization.read

Operation: staffGetOrganization · Auth: Staff + WorkosUserId

Responses: 200 The organization (StaffOrganization), 401 Unauthorized, 403 Forbidden, 404 NotFound, 429 TooManyRequests, 503 Unavailable

PATCH /v1/staff/organizations/{organization_id}

billing_exempt (unlimited free usage); audited as staff.organization.billing_exempt with before/after

Operation: staffUpdateOrganization · Auth: Staff + WorkosUserId + RequestSignature

Body (application/json, StaffOrganizationPatch, required)

Responses: 200 The organization (StaffOrganization), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

GET /v1/staff/projects

All organizations' projects, keyset

Operation: staffListProjects · Auth: Staff + WorkosUserId

Responses: 200 One page (StaffProjectList), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 429 TooManyRequests, 503 Unavailable

GET /v1/staff/projects/{slug}

One project (any organization); audited as staff.project.read

Operation: staffGetProject · Auth: Staff + WorkosUserId

Responses: 200 The project (StaffProject), 401 Unauthorized, 403 Forbidden, 404 NotFound, 429 TooManyRequests, 503 Unavailable

PATCH /v1/staff/projects/{slug}

status (staff suspension), custom_domains, storage_hard_limit_bytes (null = plan allowance), pricing_multiplier, nudity_auto_block (true -> false releases the scanner's unreviewed nudity blocks)

Operation: staffUpdateProject · Auth: Staff + WorkosUserId + RequestSignature

Body (application/json, StaffProjectPatch, required)

Responses: 200 The project (StaffProjectUpdated), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 409 Conflict, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

GET /v1/staff/projects/{slug}/files

Operation: staffListProjectFiles · Auth: Staff + WorkosUserId

Responses: 200 One page (StaffFileList), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 429 TooManyRequests, 503 Unavailable

GET /v1/staff/projects/{slug}/uploads

Operation: staffListProjectUploads · Auth: Staff + WorkosUserId

Responses: 200 One page (StaffUploadList), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 429 TooManyRequests, 503 Unavailable

GET /v1/staff/projects/{slug}/usage

Operation: staffGetProjectUsage · Auth: Staff + WorkosUserId

Responses: 200 Usage (Usage), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 429 TooManyRequests, 503 Unavailable

POST /v1/staff/files/{fileId}/block

files.status blocked + purge + file.blocked webhook; removes watermark presets using the file

Operation: staffBlockFile · Auth: Staff + WorkosUserId + RequestSignature

Body (application/json, BlockRequest, required)

Responses: 200 The file (ModerationResult), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

POST /v1/staff/files/{fileId}/unblock

Back to ready + purge + file.unblocked webhook; approves the file's checks. Body optional.

Operation: staffUnblockFile · Auth: Staff + WorkosUserId + RequestSignature

Body (application/json, UnblockRequest, optional)

Responses: 200 The file (ModerationResult), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

GET /v1/staff/moderation-notes

Operation: staffListModerationNotes · Auth: Staff + WorkosUserId

Responses: 200 One page (StaffModerationNoteList), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 429 TooManyRequests, 503 Unavailable

GET /v1/staff/reconciliation

metering_daily state per UTC day for the last 7 days (today included)

Operation: staffGetReconciliation · Auth: Staff + WorkosUserId

Responses: 200 Reconciliation state (Reconciliation), 401 Unauthorized, 403 Forbidden, 404 NotFound, 429 TooManyRequests, 503 Unavailable

GET /v1/staff/checks

Scanner checks, keyset, newest first. Audited as staff.checks.list with metadata.check_ids (the returned page's ids), which also covers the thumbnails the queue shows (staffGetCheckImage size=thumb).

Operation: staffListChecks · Auth: Staff + WorkosUserId

Responses: 200 One page (CheckList), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 429 TooManyRequests, 503 Unavailable

GET /v1/staff/checks/{id}

Operation: staffGetCheck · Auth: Staff + WorkosUserId

Responses: 200 The check and its reviews (CheckDetail), 401 Unauthorized, 403 Forbidden, 404 NotFound, 429 TooManyRequests, 503 Unavailable

GET /v1/staff/checks/{id}/image

A webp preview of the content the check scanned (the sanitized content object of its sha256, not the file's current revision), resized to fit a size x size box (thumb 480, large 1600; smaller sources are enlarged). Served even while the file is blocked. One render per api process with up to 32 waiting (503 preview_busy beyond); sources above 64 MiB are 413 preview_too_large; unrenderable content is 422 preview_unavailable; an unknown check is 404 not_found and a check whose content object is no longer stored 404 content_missing; a retryable store failure or a source read not finished within 15 s is 503 storage_unavailable. Rendered previews are cached per api process (keyed by sha256 and size): a hit reads nothing and takes no slot. Only size=large is audited, as staff.check.image (metadata.size) on success, cache hits included; thumb renders get no row of their own (the queue listing's staff.checks.list row lists the page's check ids in metadata.check_ids).

Operation: staffGetCheckImage · Auth: Staff + WorkosUserId

Responses: 200 The preview. Cache-Control private, no-store; X-Content-Type-Options nosniff; Content-Disposition inline., 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 413 PayloadTooLarge, 422 Unprocessable, 429 TooManyRequests, 503 Unavailable

POST /v1/staff/checks/{id}/review

approved unblocks a nudity-v1 block; rejected blocks a served file. Only flagged checks (409 check_not_flagged).

Operation: staffReviewCheck · Auth: Staff + WorkosUserId + RequestSignature

Body (application/json, CheckReviewRequest, required)

Responses: 200 The review (CheckReviewResult), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 409 Conflict, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

GET /v1/staff/incidents

Every incident, newest start first (keyset); audited as staff.incidents.list

Operation: staffListIncidents · Auth: Staff + WorkosUserId

Responses: 200 A page of incidents (IncidentList), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 429 TooManyRequests, 503 Unavailable

POST /v1/staff/incidents

Manual incident for the status page (auto false)

Operation: staffCreateIncident · Auth: Staff + WorkosUserId + RequestSignature

Body (application/json, IncidentCreate, required)

Responses: 201 Created (Incident), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable

PATCH /v1/staff/incidents/{id}

ended_at and/or body of a manual incident; automatic incidents are 409 incident_automatic

Operation: staffUpdateIncident · Auth: Staff + WorkosUserId + RequestSignature

Body (application/json, IncidentPatch, required)

Responses: 200 Updated (Incident), 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 409 Conflict, 413 PayloadTooLarge, 429 TooManyRequests, 503 Unavailable