jobs
Tenant-scoped durable media jobs.
| Method | Path | Operation ID |
|---|---|---|
| GET | /v1/jobs/{job_id} |
getJob |
| POST | /v1/jobs/{job_id}/cancel |
cancelJob |
| POST | /v1/sign |
acceptSigningJob |
| POST | /v1/sign/batch |
acceptSigningJobBatch |
GET /v1/jobs/{job_id}
Section titled “GET /v1/jobs/{job_id}”Operation ID: getJob
Read tenant-scoped durable status, progress, and step evidence.
Authentication: Authorization: Bearer <API key or console session> (Authentication).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
job_id |
path | string | yes | Pattern: ^job_[a-z2-7]{16}$. |
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json JobResponse |
| 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 |
|---|---|---|---|
active_plan_revision |
integer | yes | |
asset_id |
string | yes | Pattern: ^ast_[a-z2-7]{16}$. |
cancel_requested_at |
string or null | yes | |
error_code |
string or null | yes | |
job_id |
string | yes | Asynchronous Sign job identifier; poll this resource until terminal. Pattern: ^job_[a-z2-7]{16}$. |
media_inspection |
NormalizedInspectionFacts or null | yes | |
policy_version |
string | yes | |
progress |
JobProgressResponse | yes | |
recipe_id |
string | yes | |
recipe_version |
integer | yes | |
result |
JobResultResponse or null | yes | Present only for completed Sign jobs; never a polling snapshot. |
state |
JobState | yes | Sign lifecycle. completed implies result is present and result.verification_id is immutable evidence readable immediately; nonterminal states do not expose result. One of: accepted, queued, running, cancel_requested, completed, canceled, expired, rejected, failed. |
steps |
array of JobStepResponse | yes | |
terminal_at |
string or null | yes |
POST /v1/jobs/{job_id}/cancel
Section titled “POST /v1/jobs/{job_id}/cancel”Operation ID: cancelJob
Safely request cancellation without publishing through active fences.
Authentication: Authorization: Bearer <API key or console session> (Authentication).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
job_id |
path | string | yes | Pattern: ^job_[a-z2-7]{16}$. |
Idempotency-Key |
header | string | yes | Pattern: ^[!-~]+$. Max length 200. |
Request body
Section titled “Request body”application/json: CancelJobRequest (required)
| Field | Type | Required | Description |
|---|---|---|---|
reason |
string or null | no |
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json JobResponse |
| 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 |
|---|---|---|---|
active_plan_revision |
integer | yes | |
asset_id |
string | yes | Pattern: ^ast_[a-z2-7]{16}$. |
cancel_requested_at |
string or null | yes | |
error_code |
string or null | yes | |
job_id |
string | yes | Asynchronous Sign job identifier; poll this resource until terminal. Pattern: ^job_[a-z2-7]{16}$. |
media_inspection |
NormalizedInspectionFacts or null | yes | |
policy_version |
string | yes | |
progress |
JobProgressResponse | yes | |
recipe_id |
string | yes | |
recipe_version |
integer | yes | |
result |
JobResultResponse or null | yes | Present only for completed Sign jobs; never a polling snapshot. |
state |
JobState | yes | Sign lifecycle. completed implies result is present and result.verification_id is immutable evidence readable immediately; nonterminal states do not expose result. One of: accepted, queued, running, cancel_requested, completed, canceled, expired, rejected, failed. |
steps |
array of JobStepResponse | yes | |
terminal_at |
string or null | yes |
POST /v1/sign
Section titled “POST /v1/sign”Operation ID: acceptSigningJob
Accept one durable recipe job against a ready immutable asset.
Authentication: Authorization: Bearer <API key or console session> (Authentication).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key |
header | string | yes | Pattern: ^[!-~]+$. Max length 200. |
Request body
Section titled “Request body”application/json: SignRequest (required)
| Field | Type | Required | Description |
|---|---|---|---|
ai_declaration |
AiDeclarationRequest or null | no | Declare that this asset was produced with a generative model. The manifest then records c2pa.created with the digital source type you state, instead of c2pa.opened. Requires a sign-only recipe. |
asset_id |
string | yes | Tenant-visible ast_ asset identifier; never an immutable aob_ object ID. Pattern: ^ast_[a-z2-7]{16}$. |
creator_id |
string or null | no | Optional enrolled creator to attribute this output to. The manifest carries only an opaque reference and a commitment, never the creator’s name or email address. |
fingerprint_algorithms |
array of enum or null | no | The fingerprints to compute as server-side recovery signals. Omit it to use the default set GET /v1/capabilities reports for the asset’s media type. A list replaces that set: name each fingerprint once, at least one, all offered for the media type. A locked fingerprint (ISCC Image-Code for images) is always added, because it is the soft binding the manifest carries. The default applies only to new jobs: an admitted job keeps the set it was admitted with. |
mode |
enum or null | no | express runs a JPEG, PNG, WebP, TIFF or AVIF image on the express lane – the same watermark, fingerprint and C2PA manifest as rcp_system_watermark_then_sign, run as one uninterrupted job – and waits for it: the response is 200 with the completed job and a download link, or 202 with the job as usual if it has not finished within the wait (webhooks are delivered either way). It applies to rcp_system_watermark_then_sign and rcp_system_express_watermark_then_sign; any other recipe or media type runs on the ordinary pipeline and answers 202. standard, or omitting the field, is the ordinary asynchronous request. |
recipe_id |
string or null | no | The recipe to run (GET /v1/recipes). Required unless the calling API key’s signing profile names a default recipe. |
watermark_algorithm |
enum or null | no | The invisible watermark to embed, for a watermark recipe. Omit it to use the default GET /v1/capabilities reports for the asset’s media type. It must be one of the algorithms listed there for that media type; a sign-only recipe refuses it. The default applies only to new jobs: an admitted job keeps the watermark it was admitted with. Name trustmark-q to keep the TrustMark Q watermark on any image media type. |
watermark_strength |
enum or null | no | How hard the watermark may be embedded, for a watermark recipe. subtle embeds at the algorithm’s lowest qualified strength only and refuses the job rather than make it stronger; balanced is the default (omit the field for the same result); robust allows the full qualified ladder. GET /v1/capabilities lists the exact strengths each level allows for each algorithm. A sign-only recipe refuses it. An admitted job keeps the strength it was admitted with. |
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 200 | mode express only: the job finished within the wait. A completed job carries its download. | application/json ExpressSignResponse |
| 202 | Successful Response | application/json JobResponse |
| 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 |
| 402 | Payment Required | application/json ErrorResponse |
| 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 |
|---|---|---|---|
active_plan_revision |
integer | yes | |
asset_id |
string | yes | Pattern: ^ast_[a-z2-7]{16}$. |
cancel_requested_at |
string or null | yes | |
download |
DownloadResponse or null | yes | Present when the job completed and its output is deliverable; absent for a job that finished in any other state. |
error_code |
string or null | yes | |
job_id |
string | yes | Asynchronous Sign job identifier; poll this resource until terminal. Pattern: ^job_[a-z2-7]{16}$. |
media_inspection |
NormalizedInspectionFacts or null | yes | |
policy_version |
string | yes | |
progress |
JobProgressResponse | yes | |
recipe_id |
string | yes | |
recipe_version |
integer | yes | |
result |
JobResultResponse or null | yes | Present only for completed Sign jobs; never a polling snapshot. |
state |
JobState | yes | Sign lifecycle. completed implies result is present and result.verification_id is immutable evidence readable immediately; nonterminal states do not expose result. One of: accepted, queued, running, cancel_requested, completed, canceled, expired, rejected, failed. |
steps |
array of JobStepResponse | yes | |
terminal_at |
string or null | yes |
202 response fields
Section titled “202 response fields”| Field | Type | Required | Description |
|---|---|---|---|
active_plan_revision |
integer | yes | |
asset_id |
string | yes | Pattern: ^ast_[a-z2-7]{16}$. |
cancel_requested_at |
string or null | yes | |
error_code |
string or null | yes | |
job_id |
string | yes | Asynchronous Sign job identifier; poll this resource until terminal. Pattern: ^job_[a-z2-7]{16}$. |
media_inspection |
NormalizedInspectionFacts or null | yes | |
policy_version |
string | yes | |
progress |
JobProgressResponse | yes | |
recipe_id |
string | yes | |
recipe_version |
integer | yes | |
result |
JobResultResponse or null | yes | Present only for completed Sign jobs; never a polling snapshot. |
state |
JobState | yes | Sign lifecycle. completed implies result is present and result.verification_id is immutable evidence readable immediately; nonterminal states do not expose result. One of: accepted, queued, running, cancel_requested, completed, canceled, expired, rejected, failed. |
steps |
array of JobStepResponse | yes | |
terminal_at |
string or null | yes |
POST /v1/sign/batch
Section titled “POST /v1/sign/batch”Operation ID: acceptSigningJobBatch
Accept up to 100 durable recipe jobs, each admitted exactly as POST /v1/sign.
Admit up to 100 sign requests in one call, each exactly as /v1/sign would. Items are admitted in order and independently; a refused item reports its own status and error and does not roll back the others. Item i uses the idempotency key <Idempotency-Key>.b<i>, so replaying the whole batch returns the same jobs. A rate-limited key spends one request per item.
Authentication: Authorization: Bearer <API key or console session> (Authentication).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key |
header | string | yes | Pattern: ^[!-~]+$. Max length 196. |
Request body
Section titled “Request body”application/json: SignBatchRequest (required)
| Field | Type | Required | Description |
|---|---|---|---|
items |
array of SignRequest | yes | Between 1 and 100 sign requests, each exactly what POST /v1/sign accepts. Every item is admitted on its own: one item’s refusal does not affect the others. Items are always admitted asynchronously: an item’s mode is ignored. |
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 202 | Successful Response | application/json SignBatchResponse |
| 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. |
application/json HttpErrorResponse or ErrorResponse |
| 409 | Just-in-time provisioning conflicted: the verified email belongs to another provisioned account. | application/json HttpErrorResponse |
| 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 |
202 response fields
Section titled “202 response fields”| Field | Type | Required | Description |
|---|---|---|---|
items |
array of SignBatchItemResponse | yes | One result per item, in request order. |