assets
Tenant-scoped publication, download, receipt, and webhook evidence.
| Method | Path | Operation ID |
|---|---|---|
| GET | /v1/assets/{asset_id} |
getAsset |
| POST | /v1/assets/{asset_id}/download |
createAssetDownload |
| POST | /v1/assets/{asset_id}/preview |
createAssetPreview |
| GET | /v1/assets/{asset_id}/preview/{capability} |
redeemAssetPreview |
| GET | /v1/receipts/{receipt_id} |
getSigningReceipt |
| POST | /v1/webhook-events/{event_id}/replay |
replayWebhookEvent |
GET /v1/assets/{asset_id}
Section titled “GET /v1/assets/{asset_id}”Operation ID: getAsset
Read tenant-scoped asset state and validated publication metadata.
Authentication: Authorization: Bearer <API key or console session> (Authentication).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
asset_id |
path | string | yes | Pattern: ^ast_[a-z2-7]{16}$. |
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json AssetResponse |
| 401 | The bearer credential is missing, malformed, expired, revoked, or otherwise invalid. Clerk sessions and scoped API keys fail identically and the body never reveals which credential was presented or whether it exists. | application/json HttpErrorResponse |
| 403 | The provider deleted this identity, or the account is deactivated. A valid session cannot authorize a tombstoned identity back into use; an API key must also grant the scope required by the operation, and an operation is not classified by the route/scope policy and is denied by default. An API key restricted to client networks is refused from any other network with the API_KEY_IP_NOT_ALLOWED envelope. This operation may also return its reason-coded domain envelope with this status. |
application/json HttpErrorResponse or ErrorResponse |
| 404 | Not Found | application/json ErrorResponse |
| 409 | Just-in-time provisioning conflicted: the verified email belongs to another provisioned account. This operation may also return its reason-coded domain envelope with this status. | application/json HttpErrorResponse or ErrorResponse |
| 422 | A verified email is unavailable for account provisioning. This operation may also return its reason-coded domain envelope with this status. | application/json HttpErrorResponse or ErrorResponse |
| 429 | The API key’s own request rate limit was exceeded (API_KEY_RATE_LIMITED). Only keys configured with a rate limit can receive this. Retryable after Retry-After seconds; the refused request consumed no capacity. |
application/json ErrorResponse |
| 503 | Credential verification is unavailable: Clerk session verification is not configured, no API-key pepper is enrolled, or bounded API-key verification is temporarily overloaded. Retryable. This operation may also return its reason-coded domain envelope with this status. | application/json HttpErrorResponse or ErrorResponse |
200 response fields
Section titled “200 response fields”| Field | Type | Required | Description |
|---|---|---|---|
asset_id |
string | yes | |
created_at |
string | yes | |
kind |
string | yes | |
media_type |
string or null | yes | |
publication |
PublicationResponse or null | yes | |
status |
string | yes |
POST /v1/assets/{asset_id}/download
Section titled “POST /v1/assets/{asset_id}/download”Operation ID: createAssetDownload
Create a short-lived GET capability for the exact validated S3 version.
Authentication: Authorization: Bearer <API key or console session> (Authentication).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
asset_id |
path | string | yes | Pattern: ^ast_[a-z2-7]{16}$. |
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json DownloadResponse |
| 401 | The bearer credential is missing, malformed, expired, revoked, or otherwise invalid. Clerk sessions and scoped API keys fail identically and the body never reveals which credential was presented or whether it exists. | application/json HttpErrorResponse |
| 403 | The provider deleted this identity, or the account is deactivated. A valid session cannot authorize a tombstoned identity back into use; an API key must also grant the scope required by the operation, and an operation is not classified by the route/scope policy and is denied by default. An API key restricted to client networks is refused from any other network with the API_KEY_IP_NOT_ALLOWED envelope. This operation may also return its reason-coded domain envelope with this status. |
application/json HttpErrorResponse or ErrorResponse |
| 404 | Not Found | application/json ErrorResponse |
| 409 | Just-in-time provisioning conflicted: the verified email belongs to another provisioned account. This operation may also return its reason-coded domain envelope with this status. | application/json HttpErrorResponse or ErrorResponse |
| 422 | A verified email is unavailable for account provisioning. This operation may also return its reason-coded domain envelope with this status. | application/json HttpErrorResponse or ErrorResponse |
| 429 | The API key’s own request rate limit was exceeded (API_KEY_RATE_LIMITED). Only keys configured with a rate limit can receive this. Retryable after Retry-After seconds; the refused request consumed no capacity. |
application/json ErrorResponse |
| 503 | Credential verification is unavailable: Clerk session verification is not configured, no API-key pepper is enrolled, or bounded API-key verification is temporarily overloaded. Retryable. This operation may also return its reason-coded domain envelope with this status. | application/json HttpErrorResponse or ErrorResponse |
200 response fields
Section titled “200 response fields”| Field | Type | Required | Description |
|---|---|---|---|
byte_length |
integer | yes | Immutable byte length of the exact published object. This field is always present on a successful authenticated download response. |
expires_at |
string | yes | |
filename |
string | yes | The name to save the asset under: the asset id plus the container’s own extension, so a signed audio/mp4 arrives as .m4a rather than .mp4. Added 2026-09-22 because the contract already described this value without exposing it – sidecar_manifest.filename is documented as ‘the asset’s own download filename plus .c2pa’, and that filename was computed and then dropped. |
headers |
object | yes | |
media_type |
enum | yes | One of: application/epub+zip, application/onnx, application/oxps, application/pdf, application/vnd.oasis.opendocument.text, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/x-jax, application/x-keras, application/x-mlnet, application/x-mxnet, application/x-npy, application/x-openvino-ir+xml, application/x-openvino-weights, application/x-pickle, application/x-protobuf, application/x-pytorch, application/x-tensorflow, application/x-tensorflow-savedmodel, application/x-zip-based, application/xhtml+xml, application/xml, audio/MPA, audio/aac, audio/flac, audio/mp4, audio/mpeg, audio/wav, audio/x-riff-based, font/otf, image/avif, image/gif, image/heic, image/heic-sequence, image/heif, image/heif-sequence, image/jpeg, image/jxl, image/png, image/svg+xml, image/tiff, image/webp, image/x-adobe-dng, image/x-riff-based, image/x-tiff-based, text/html, text/plain, text/xml, video/mp4, video/quicktime, video/x-bmff-based, video/x-msvideo, video/x-riff-based. |
method |
const “GET” | yes | |
sha256 |
string | yes | Lowercase SHA-256 of the exact published bytes. This field is always present on a successful authenticated download response. Pattern: ^[0-9a-f]{64}$. |
sidecar_manifest |
SidecarManifestResponse or null | no | Present when the asset’s manifest travels beside it rather than inside it (the sidecar lane; the formats are listed by GET /v1/capabilities). Absent for every embedded format. |
storage_version_sha256 |
string | yes | |
url |
string | yes |
POST /v1/assets/{asset_id}/preview
Section titled “POST /v1/assets/{asset_id}/preview”Operation ID: createAssetPreview
Create a short-lived GET capability for the asset’s governed preview derivative.
Mint one short-lived delivery for this asset’s preview derivative. A POST rather than a GET because it mints a new credential-bearing delivery every time; nothing about it is cacheable, and treating it as a read would invite exactly the caching a short-lived URL exists to avoid.
Authentication: Authorization: Bearer <API key or console session> (Authentication).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
asset_id |
path | string | yes | Pattern: ^ast_[a-z2-7]{16}$. |
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json PreviewResponse |
| 401 | The bearer credential is missing, malformed, expired, revoked, or otherwise invalid. Clerk sessions and scoped API keys fail identically and the body never reveals which credential was presented or whether it exists. | application/json HttpErrorResponse |
| 403 | The provider deleted this identity, or the account is deactivated. A valid session cannot authorize a tombstoned identity back into use; an API key must also grant the scope required by the operation, and an operation is not classified by the route/scope policy and is denied by default. An API key restricted to client networks is refused from any other network with the API_KEY_IP_NOT_ALLOWED envelope. This operation may also return its reason-coded domain envelope with this status. |
application/json HttpErrorResponse or ErrorResponse |
| 404 | Not Found | application/json ErrorResponse |
| 409 | Just-in-time provisioning conflicted: the verified email belongs to another provisioned account. This operation may also return its reason-coded domain envelope with this status. | application/json HttpErrorResponse or ErrorResponse |
| 422 | A verified email is unavailable for account provisioning. This operation may also return its reason-coded domain envelope with this status. | application/json HttpErrorResponse or ErrorResponse |
| 429 | The API key’s own request rate limit was exceeded (API_KEY_RATE_LIMITED). Only keys configured with a rate limit can receive this. Retryable after Retry-After seconds; the refused request consumed no capacity. |
application/json ErrorResponse |
| 503 | Credential verification is unavailable: Clerk session verification is not configured, no API-key pepper is enrolled, or bounded API-key verification is temporarily overloaded. Retryable. This operation may also return its reason-coded domain envelope with this status. | application/json HttpErrorResponse or ErrorResponse |
200 response fields
Section titled “200 response fields”| Field | Type | Required | Description |
|---|---|---|---|
byte_length |
integer | yes | |
expires_at |
string | yes | |
headers |
object | yes | |
height |
integer | yes | |
media_type |
const “image/jpeg” | yes | |
method |
const “GET” | yes | |
sha256 |
string | yes | Pattern: ^[0-9a-f]{64}$. |
url |
string | yes | |
width |
integer | yes |
GET /v1/assets/{asset_id}/preview/{capability}
Section titled “GET /v1/assets/{asset_id}/preview/{capability}”Operation ID: redeemAssetPreview
Redeem one preview-only URL capability after fresh governance and version checks.
Redeem one bearer locator after re-authorizing every governed fact.
Authentication: none (anonymous).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
asset_id |
path | string | yes | Pattern: ^ast_[a-z2-7]{16}$. |
capability |
path | string | yes | Pattern: ^[A-Za-z0-9_-]+$. Max length 1024. |
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 200 | Exact preview derivative bytes. | image/jpeg any |
| 404 | The capability is malformed, expired, withdrawn, tenant-mismatched, or no longer names the exact preview derivative. Every case returns the same typed response. | application/json ErrorResponse |
GET /v1/receipts/{receipt_id}
Section titled “GET /v1/receipts/{receipt_id}”Operation ID: getSigningReceipt
Read the privacy-safe immutable receipt for one validated publication.
Authentication: Authorization: Bearer <API key or console session> (Authentication).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
receipt_id |
path | string | yes | Pattern: ^rct_[a-z2-7]{16}$. |
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json ReceiptResponse |
| 401 | The bearer credential is missing, malformed, expired, revoked, or otherwise invalid. Clerk sessions and scoped API keys fail identically and the body never reveals which credential was presented or whether it exists. | application/json HttpErrorResponse |
| 403 | The provider deleted this identity, or the account is deactivated. A valid session cannot authorize a tombstoned identity back into use; an API key must also grant the scope required by the operation, and an operation is not classified by the route/scope policy and is denied by default. An API key restricted to client networks is refused from any other network with the API_KEY_IP_NOT_ALLOWED envelope. This operation may also return its reason-coded domain envelope with this status. |
application/json HttpErrorResponse or ErrorResponse |
| 404 | Not Found | application/json ErrorResponse |
| 409 | Just-in-time provisioning conflicted: the verified email belongs to another provisioned account. This operation may also return its reason-coded domain envelope with this status. | application/json HttpErrorResponse or ErrorResponse |
| 422 | A verified email is unavailable for account provisioning. This operation may also return its reason-coded domain envelope with this status. | application/json HttpErrorResponse or ErrorResponse |
| 429 | The API key’s own request rate limit was exceeded (API_KEY_RATE_LIMITED). Only keys configured with a rate limit can receive this. Retryable after Retry-After seconds; the refused request consumed no capacity. |
application/json ErrorResponse |
| 503 | Credential verification is unavailable: Clerk session verification is not configured, no API-key pepper is enrolled, or bounded API-key verification is temporarily overloaded. Retryable. This operation may also return its reason-coded domain envelope with this status. | application/json HttpErrorResponse or ErrorResponse |
200 response fields
Section titled “200 response fields”| Field | Type | Required | Description |
|---|---|---|---|
asset_id |
string | yes | |
created_at |
string | yes | |
evidence |
LegacySigningReceiptEvidenceResponse or SigningReceiptEvidenceResponse or SidecarSigningReceiptEvidenceResponse or RecoveredSigningReceiptEvidenceResponse or BindingReceiptEvidenceResponse | yes | |
job_id |
string | yes | |
receipt_id |
string | yes |
POST /v1/webhook-events/{event_id}/replay
Section titled “POST /v1/webhook-events/{event_id}/replay”Operation ID: replayWebhookEvent
Authorize idempotent redelivery of one tenant-owned immutable webhook event.
Authentication: Authorization: Bearer <API key or console session> (Authentication).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
event_id |
path | string | yes | Pattern: ^whevt_[a-z2-7]{16}$. |
Idempotency-Key |
header | string | yes | Pattern: ^[!-~]+$. Max length 200. |
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json WebhookReplayResponse |
| 401 | The bearer credential is missing, malformed, expired, revoked, or otherwise invalid. Clerk sessions and scoped API keys fail identically and the body never reveals which credential was presented or whether it exists. | application/json HttpErrorResponse |
| 403 | The provider deleted this identity, or the account is deactivated. A valid session cannot authorize a tombstoned identity back into use; an API key must also grant the scope required by the operation, and an operation is not classified by the route/scope policy and is denied by default. An API key restricted to client networks is refused from any other network with the API_KEY_IP_NOT_ALLOWED envelope. This operation may also return its reason-coded domain envelope with this status. |
application/json HttpErrorResponse or ErrorResponse |
| 404 | Not Found | application/json ErrorResponse |
| 409 | Just-in-time provisioning conflicted: the verified email belongs to another provisioned account. This operation may also return its reason-coded domain envelope with this status. | application/json HttpErrorResponse or ErrorResponse |
| 422 | A verified email is unavailable for account provisioning. This operation may also return its reason-coded domain envelope with this status. | application/json HttpErrorResponse or ErrorResponse |
| 429 | The API key’s own request rate limit was exceeded (API_KEY_RATE_LIMITED). Only keys configured with a rate limit can receive this. Retryable after Retry-After seconds; the refused request consumed no capacity. |
application/json ErrorResponse |
| 503 | Credential verification is unavailable: Clerk session verification is not configured, no API-key pepper is enrolled, or bounded API-key verification is temporarily overloaded. Retryable. This operation may also return its reason-coded domain envelope with this status. | application/json HttpErrorResponse or ErrorResponse |
200 response fields
Section titled “200 response fields”| Field | Type | Required | Description |
|---|---|---|---|
delivery_count |
integer | yes | |
event_id |
string | yes |