API reference
Original Pictures API version 1.0.0 (OpenAPI 3.1.0). Versioned public and operational contract. Media transfers use restricted direct-to-object-storage requests; bucket names, keys, and storage version IDs are never response fields.
This reference lists all 109 operations in the contract. Guides such as the Quickstart explain how the operations fit together.
system
Section titled “system”Anonymous process, dependency-health, and deployment-readiness probes.
| Method | Path | Summary |
|---|---|---|
| GET | /healthz |
Read process liveness without probing downstream dependencies. |
| GET | /healthz/db |
Probe bounded database connectivity without touching product data. |
| GET | /readyz |
Read rolling-deployment readiness across required runtime adapters. |
| GET | /readyz/governance |
Read destructive-governance capability readiness without gating unrelated traffic. |
identity
Section titled “identity”Authenticated caller identity and account context.
| Method | Path | Summary |
|---|---|---|
| GET | /v1/me |
Read the authenticated caller’s provisioned public identity. |
connect
Section titled “connect”Public integration catalog and tenant developer-onboarding state.
| Method | Path | Summary |
|---|---|---|
| GET | /v1/connect-catalog |
Read the public versioned Connect catalog for human and prompt renderers. |
| GET | /v1/developer-onboarding |
Read secret-free tenant setup and API-key request-observation state. |
api-keys
Section titled “api-keys”Scoped server credential issuance, rotation, revocation, and audit.
| Method | Path | Summary |
|---|---|---|
| GET | /v1/api-keys |
List tenant-owned API-key metadata without credential secrets. |
| POST | /v1/api-keys |
Issue a scoped API key and display its secret exactly once. |
| GET | /v1/api-keys/scopes |
Discover the exact versioned scope vocabulary an API key may be granted. |
| GET | /v1/api-keys/{api_key_id} |
Read one tenant-owned API key’s metadata without credential secrets. |
| DELETE | /v1/api-keys/{api_key_id} |
Immediately revoke one tenant-owned API key. |
| GET | /v1/api-keys/{api_key_id}/restrictions |
Read the key’s versioned IP allowlist and rate limit. |
| PUT | /v1/api-keys/{api_key_id}/restrictions |
Replace the key’s IP allowlist and rate limit, effective from its next request. |
| GET | /v1/api-keys/{api_key_id}/retention |
Read the key’s versioned retention policy without changing historical jobs. |
| PUT | /v1/api-keys/{api_key_id}/retention |
Set retention for future admissions within tenant and delegated-key ceilings. |
| POST | /v1/api-keys/{api_key_id}/rotate |
Begin a bounded API-key rollover and display the successor secret once. |
| POST | /v1/api-keys/{api_key_id}/rotation/cancel |
Cancel a pending rollover and revoke its undeployed successor. |
| POST | /v1/api-keys/{api_key_id}/rotation/complete |
Retire an outgoing API key after its successor has been deployed. |
| GET | /v1/api-keys/{api_key_id}/signing-profile |
Read the key’s versioned signing defaults and allowed sets. |
| PUT | /v1/api-keys/{api_key_id}/signing-profile |
Replace the key’s signing defaults and allowed sets, effective from its next Sign. |
| GET | /v1/api-request-logs |
List the tenant’s recent API-key requests (metadata only, best effort). |
| GET | /v1/api-request-logs/summary |
Summarize the tenant’s recent API-key requests by status and latency. |
uploads
Section titled “uploads”Tenant-scoped immutable upload lifecycle.
| Method | Path | Summary |
|---|---|---|
| POST | /v1/uploads |
Create an expiring tenant-scoped direct upload session. |
| POST | /v1/uploads/{upload_id}/abort |
Abort an initiated upload and remove its exact staging capability. |
| POST | /v1/uploads/{upload_id}/complete |
Verify and conditionally pin the exact immutable object. |
capture
Section titled “capture”Privacy-safe capture identities, admission decisions, and revocation.
| Method | Path | Summary |
|---|---|---|
| POST | /v1/capture-admission-challenges |
Create one purpose-bound capture-admission challenge. |
| GET | /v1/capture-admissions |
List bounded privacy-safe capture admissions. |
| POST | /v1/capture-admissions |
Create or exactly replay one terminal capture admission. |
| GET | /v1/capture-admissions/{capture_admission_id} |
Read one privacy-safe capture admission detail. |
| GET | /v1/capture-identities |
List bounded privacy-safe capture identities. |
| POST | /v1/capture-identities |
Complete one capture-identity enrollment or replay its exact target. |
| GET | /v1/capture-identities/{capture_identity_id} |
Read one privacy-safe capture identity detail. |
| POST | /v1/capture-identities/{capture_identity_id}/revoke |
Terminally revoke one owned capture identity. |
| POST | /v1/capture-identity-enrollments |
Create one purpose-bound capture-identity enrollment challenge. |
creators
Section titled “creators”Creator identities attributed in content credentials, their disclosure policy, and authorized disclosure.
| Method | Path | Summary |
|---|---|---|
| GET | /v1/creator-disclosure-policy |
Read this tenant’s creator disclosure policy. |
| PUT | /v1/creator-disclosure-policy |
Set this tenant’s brand name and creator disclosure policy. |
| GET | /v1/creator-identities |
List this tenant’s enrolled creator identities. |
| POST | /v1/creator-identities |
Enrol one creator identity for later attribution. |
| GET | /v1/creator-identities/{creator_identity_id} |
Read one enrolled creator identity. |
| GET | /v1/creator-identities/{creator_identity_id}/disclosure |
Disclose one creator’s details to the owning tenant. |
| POST | /v1/creator-identities/{creator_identity_id}/withdraw |
Stop disclosing one creator identity without erasing it. |
Tenant-scoped durable media jobs.
| Method | Path | Summary |
|---|---|---|
| GET | /v1/jobs/{job_id} |
Read tenant-scoped durable status, progress, and step evidence. |
| POST | /v1/jobs/{job_id}/cancel |
Safely request cancellation without publishing through active fences. |
| POST | /v1/sign |
Accept one durable recipe job against a ready immutable asset. |
| POST | /v1/sign/batch |
Accept up to 100 durable recipe jobs, each admitted exactly as POST /v1/sign. |
history
Section titled “history”Snapshot-consistent tenant asset, job, receipt, and verification history.
| Method | Path | Summary |
|---|---|---|
| GET | /v1/assets |
List a bounded snapshot-consistent page of tenant assets. |
| GET | /v1/assets/{asset_id}/detail |
Read one asset’s complete record: identity, media, related records, verification history, activity, governance and action state. |
| DELETE | /v1/history/snapshots |
Release one live opaque history traversal before its bounded expiry. |
| GET | /v1/jobs |
List a bounded snapshot-consistent page of tenant jobs and progress. |
| GET | /v1/receipts |
List a bounded snapshot-consistent page of tenant publication receipts. |
| GET | /v1/verification-history/{verification_id} |
Read one tenant-owned historical verification summary and validation path. |
| GET | /v1/verifications |
List a bounded snapshot-consistent page of tenant verification observations. |
recipes
Section titled “recipes”Enabled customer-safe recipe capabilities and supported media.
| Method | Path | Summary |
|---|---|---|
| GET | /v1/capabilities |
Read privacy-safe configured and currently available runtime capabilities. |
| GET | /v1/image-profiles |
List every reviewed image profile with its accepted capability, planned envelope, limits, and availability. |
| GET | /v1/recipes |
List the enabled reviewed recipes, with display names, and their media formats. |
| GET | /v1/recipes/{recipe_id} |
Read one exact active version from the approved immutable recipe catalog. |
verify
Section titled “verify”Stored-object verification, recovery, reports, and revocable sharing.
| Method | Path | Summary |
|---|---|---|
| GET | /v1/shared-verifications/{token} |
Read the minimal projection authorized by an unexpired share capability. |
| GET | /v1/verification-evidence/{verification_id} |
Read complete privacy-safe evidence while keeping vjob and vfy identity distinct. |
| POST | /v1/verification-evidence/{verification_id}/reports |
Generate a deterministic evidence-derived machine or human report. |
| GET | /v1/verification-evidence/{verification_id}/shares |
List share lifecycle metadata without bearer capabilities or secret URLs. |
| POST | /v1/verification-evidence/{verification_id}/shares |
Issue one expiring revocable capability for a minimal verification projection. |
| GET | /v1/verification-reports/{report_id} |
Download one tenant-owned immutable evidence-derived report. |
| POST | /v1/verification-shares/{share_id}/close |
Revoke or unpublish a verification share capability. |
| POST | /v1/verifications |
Accept an immutable stored object for asynchronous public validation. |
| GET | /v1/verifications/{verification_id} |
Read durable direct-validation and subordinate recovery status. |
assets
Section titled “assets”Tenant-scoped publication, download, receipt, and webhook evidence.
| Method | Path | Summary |
|---|---|---|
| GET | /v1/assets/{asset_id} |
Read tenant-scoped asset state and validated publication metadata. |
| POST | /v1/assets/{asset_id}/download |
Create a short-lived GET capability for the exact validated S3 version. |
| POST | /v1/assets/{asset_id}/preview |
Create a short-lived GET capability for the asset’s governed preview derivative. |
| GET | /v1/assets/{asset_id}/preview/{capability} |
Redeem one preview-only URL capability after fresh governance and version checks. |
| GET | /v1/receipts/{receipt_id} |
Read the privacy-safe immutable receipt for one validated publication. |
| POST | /v1/webhook-events/{event_id}/replay |
Authorize idempotent redelivery of one tenant-owned immutable webhook event. |
integrations
Section titled “integrations”Tenant-scoped outbound webhook endpoints, deliveries, and replay.
| Method | Path | Summary |
|---|---|---|
| GET | /v1/webhook-endpoints |
List bounded tenant-owned outbound webhook endpoints. |
| POST | /v1/webhook-endpoints |
Create a policy-approved endpoint and issue its write-only signing secret. |
| GET | /v1/webhook-endpoints/deliveries/{delivery_id} |
Read one tenant-owned delivery’s state and response evidence. |
| GET | /v1/webhook-endpoints/deliveries/{delivery_id}/attempts |
List bounded append-only attempt evidence for one delivery. |
| POST | /v1/webhook-endpoints/deliveries/{delivery_id}/replay |
Authorize delivery of the original immutable customer event again. |
| GET | /v1/webhook-endpoints/event-catalog |
Discover the exact versioned events an endpoint may subscribe to. |
| GET | /v1/webhook-endpoints/{endpoint_id} |
Read one exact tenant-owned endpoint, including a retained deleted one. |
| DELETE | /v1/webhook-endpoints/{endpoint_id} |
Soft-delete an endpoint and visibly fence its unfinished deliveries. |
| PATCH | /v1/webhook-endpoints/{endpoint_id} |
Update a destination, exact subscriptions, or bounded delivery controls. |
| GET | /v1/webhook-endpoints/{endpoint_id}/deliveries |
List bounded delivery state and response evidence for one endpoint. |
| POST | /v1/webhook-endpoints/{endpoint_id}/disable |
Disable an endpoint and visibly terminate its unfinished deliveries. |
| POST | /v1/webhook-endpoints/{endpoint_id}/enable |
Return a disabled endpoint to service after revalidating its destination. |
| POST | /v1/webhook-endpoints/{endpoint_id}/rotate-secret |
Begin bounded dual signing and reveal the new signing secret once. |
| POST | /v1/webhook-endpoints/{endpoint_id}/secret-overlap/complete |
Retire the outgoing webhook signer after its replacement is deployed. |
| POST | /v1/webhook-endpoints/{endpoint_id}/test |
Queue a synthetic signed test event for this one endpoint, ten per hour at most. |
webhooks
Section titled “webhooks”Provider-authenticated inbound webhook callbacks.
| Method | Path | Summary |
|---|---|---|
| POST | /webhooks/clerk |
Receive one Svix-signed Clerk user-lifecycle callback. |
| POST | /webhooks/stripe |
Authenticate and durably enqueue one tenant-free Stripe lifecycle event. |
billing
Section titled “billing”Tenant usage, quota and provider-intent lifecycle.
| Method | Path | Summary |
|---|---|---|
| GET | /v1/billing/account |
Read the system-owned commercial account projection. |
| GET | /v1/billing/charges |
Read immutable processing charges for explicitly enrolled tenant pricing. |
| POST | /v1/billing/checkout-intents |
Create a short-lived provider checkout redirect intent. |
| GET | /v1/billing/plans |
List the plans a checkout can buy and whether checkout is actionable. |
| POST | /v1/billing/portal-intents |
Create a short-lived provider billing-portal redirect intent. |
| GET | /v1/billing/pricing |
Read the versioned USD rate catalog without activating customer billing. |
| POST | /v1/billing/quotes |
Estimate processing from supplied facts; no payment or ledger write occurs. |
| GET | /v1/billing/wallet |
Read the prepaid wallet balance, settings and recent ledger. |
| PUT | /v1/billing/wallet/settings |
Opt into prepaid wallet billing or change auto-recharge and the monthly limit. |
| GET | /v1/usage |
Read authoritative itemized usage and hard-cap availability. |
overview
Section titled “overview”Tenant activity, health, quota, and governance rollups.
| Method | Path | Summary |
|---|---|---|
| GET | /v1/overview |
Read reviewed tenant rollups composed with bounded current authoritative state. |
governance
Section titled “governance”Tenant export, deletion, legal-hold visibility, audit, and feedback.
| Method | Path | Summary |
|---|---|---|
| POST | /v1/feedback |
Submit feedback with authorized typed resource references. |
| GET | /v1/governance/audit |
Query the tenant-scoped immutable audit projection. |
| GET | /v1/governance/deletions |
List a stable tenant-owned page of governance deletion requests. |
| POST | /v1/governance/deletions |
Request account- or asset-scoped governance deletion. |
| GET | /v1/governance/deletions/{deletion_id} |
Read one tenant-owned deletion workflow. |
| GET | /v1/governance/exports |
List a stable tenant-owned page of account export metadata. |
| POST | /v1/governance/exports |
Seal an exact-version snapshot for tenant account export. |
| GET | /v1/governance/exports/{export_id} |
Deliver integrity-checked exact-version export capabilities. |
| GET | /v1/governance/legal-holds |
List tenant-visible active and released legal holds. |
See also: Reason codes.