Operation details
GET /v1/jobs
Page through jobs in the authenticated tenant scope
- operationId
listTenantJobs- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：jobs.read
Description (from the contract)
Requires a tenant-scoped identity with jobs.read. Scope is derived only from the authenticated identity. Supplying tenant_id is an attempted scope override and returns 403.
Parameters
listTenantJobs Parameters| Name | In | Type | Required | Description |
|---|
from | query | string(date-time) | Yes | Inclusive RFC3339 creation-time bound. |
|---|
to | query | string(date-time) | Yes | Exclusive RFC3339 creation-time bound; from-to may not exceed 31 days. |
|---|
status | query | array<string: queued / running / succeeded / partial_failed / failed / cancelled> | No | Comma-separated job states; duplicates are rejected. |
|---|
task_id | query | string(uuid) | No | Exact task UUID filter. |
|---|
kind | query | string | No | — |
|---|
resource | query | string | No | Exact match against the canonical job subject/reference, or a case-insensitive match against a node UUID assigned to one of the job's items, so node pages can deep-link to the tasks executed on that node. |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | Opaque, authenticated, versioned HMAC-SHA256 keyset cursor from the preceding response, bound to route scope, endpoint, task, and filters. Reuse with changed inputs or any token modification returns 400. |
|---|
page | query | integer | No | Explicit canonical positive decimal page number, mutually exclusive with cursor even if cursor is empty. Count and rows use one read-only repeatable-read snapshot. Different requests are live snapshots and may move rows as jobs are inserted or change state. A page beyond the end returns an empty data array, the requested number and the exact total. |
|---|
Responses
listTenantJobs Responses| Status | Description |
|---|
200 | Authenticated keyset page or explicit numbered page with a same-snapshot exact total. Fields：data: array<Job> page: Page | NumberedPage query: QueryWindow task_metadata?: array<TaskMetadata> |
|---|
400 | job_invalid_request: invalid UUID, query input, Idempotency-Key, content type, or exact empty JSON command body. |
|---|
401 | job_authentication_required: authentication is missing or invalid. |
|---|
403 | job_permission_denied or job_scope_forbidden: permission is missing, audience is incompatible, or the caller attempted a scope override. |
|---|
408 | job_request_cancelled: the inbound request context was cancelled. |
|---|
502 | job_store_invalid_response or job_response_too_large: stored facts were invalid or the bounded response was too large. |
|---|
503 | job_store_unavailable: PostgreSQL or the configured Reader is unavailable. |
|---|
504 | job_query_timeout: the bounded request timed out. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/jobs/kinds
Read the integrated producer catalog as a tenant
- operationId
listTenantJobKinds- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：jobs.read
Description (from the contract)
Requires a tenant-scoped identity with jobs.read. Accepts no query parameters. Contains no tenant jobs or counts and does not claim runtime availability. Runtime status remains unknown until separately verified.
Responses
listTenantJobKinds Responses| Status | Description |
|---|
200 | Registered source-backed producer kinds, independent of current job rows or runtime enablement. Fields：data: array<JobKind> |
|---|
400 | job_invalid_request: invalid UUID, query input, Idempotency-Key, content type, or exact empty JSON command body. |
|---|
401 | job_authentication_required: authentication is missing or invalid. |
|---|
403 | job_permission_denied or job_scope_forbidden: permission is missing, audience is incompatible, or the caller attempted a scope override. |
|---|
408 | job_request_cancelled: the inbound request context was cancelled. |
|---|
502 | job_store_invalid_response or job_response_too_large: stored facts were invalid or the bounded response was too large. |
|---|
504 | job_query_timeout: the bounded request timed out. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
↑ Back to list
GET /v1/jobs/{task_id}
Read a job in the authenticated tenant scope
- operationId
getTenantJob- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：jobs.read
Description (from the contract)
A missing or cross-tenant task_id returns the same 404 response.
Parameters
getTenantJob Parameters| Name | In | Type | Required | Description |
|---|
task_id | path | string(uuid) | Yes | Canonical lower-case UUID of the background job. |
|---|
Responses
getTenantJob Responses| Status | Description |
|---|
200 | Job projection without producer payload or credentials. Fields：data: Job |
|---|
400 | job_invalid_request: invalid UUID, query input, Idempotency-Key, content type, or exact empty JSON command body. |
|---|
401 | job_authentication_required: authentication is missing or invalid. |
|---|
403 | job_permission_denied or job_scope_forbidden: permission is missing, audience is incompatible, or the caller attempted a scope override. |
|---|
404 | job_not_found: the task does not exist or is outside the authenticated tenant scope. |
|---|
408 | job_request_cancelled: the inbound request context was cancelled. |
|---|
502 | job_store_invalid_response or job_response_too_large: stored facts were invalid or the bounded response was too large. |
|---|
503 | job_store_unavailable: PostgreSQL or the configured Reader is unavailable. |
|---|
504 | job_query_timeout: the bounded request timed out. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/jobs/{task_id}/attempts
Page through a tenant job's immutable attempt history
- operationId
listTenantJobAttempts- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：jobs.read
Parameters
listTenantJobAttempts Parameters| Name | In | Type | Required | Description |
|---|
task_id | path | string(uuid) | Yes | Canonical lower-case UUID of the background job. |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | Opaque, authenticated, versioned HMAC-SHA256 keyset cursor from the preceding response, bound to route scope, endpoint, task, and filters. Reuse with changed inputs or any token modification returns 400. |
|---|
Responses
listTenantJobAttempts Responses| Status | Description |
|---|
200 | Attempt history ordered by attempt number descending. Fields：data: array<Attempt> page: Page |
|---|
400 | job_invalid_request: invalid UUID, query input, Idempotency-Key, content type, or exact empty JSON command body. |
|---|
401 | job_authentication_required: authentication is missing or invalid. |
|---|
403 | job_permission_denied or job_scope_forbidden: permission is missing, audience is incompatible, or the caller attempted a scope override. |
|---|
404 | job_not_found: the task does not exist or is outside the authenticated tenant scope. |
|---|
408 | job_request_cancelled: the inbound request context was cancelled. |
|---|
502 | job_store_invalid_response or job_response_too_large: stored facts were invalid or the bounded response was too large. |
|---|
503 | job_store_unavailable: PostgreSQL or the configured Reader is unavailable. |
|---|
504 | job_query_timeout: the bounded request timed out. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/jobs/{task_id}/cancel
Cancel a queued or running job in the authenticated tenant
- operationId
cancelTenantJob- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：jobs.manage
Description (from the contract)
Requires jobs.manage. Scope is derived only from the authenticated identity. The transition, audit, and receipt commit atomically. The same actor and Idempotency-Key return the immutable first successful snapshot with replayed=true; reuse for another command returns 409.
Parameters
cancelTenantJob Parameters| Name | In | Type | Required | Description |
|---|
task_id | path | string(uuid) | Yes | Canonical lower-case UUID of the background job. |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
If-Match | header | string | Yes | Strong ETag value returned by the latest job detail or command response. |
|---|
Request body
application/json · Required：Yes
Responses
cancelTenantJob Responses| Status | Description |
|---|
200 | Immutable cancelled or queued command result snapshot. Fields：data: Job replayed: boolean |
|---|
400 | job_invalid_request: invalid UUID, query input, Idempotency-Key, content type, or exact empty JSON command body. |
|---|
401 | job_authentication_required: authentication is missing or invalid. |
|---|
403 | job_permission_denied or job_scope_forbidden: permission is missing, audience is incompatible, or the caller attempted a scope override. |
|---|
404 | job_not_found: the task does not exist or is outside the authenticated tenant scope. |
|---|
408 | job_request_cancelled: the inbound request context was cancelled. |
|---|
409 | job_idempotency_conflict, job_invalid_transition, job_retries_exhausted, or job_producer_command_required: the key was reused for another command, the job changed or is ineligible, no retry attempt remains, or the job's producer owns the command. cache.operation cancel/retry is executed by the cache module (same audit and receipt as the cache operation API); job_producer_command_required is returned only for its replay, or when cache control is not enabled. |
|---|
412 | job_revision_conflict: the If-Match revision is stale; refresh the job before retrying. |
|---|
502 | job_store_invalid_response or job_response_too_large: stored facts were invalid or the bounded response was too large. |
|---|
503 | job_store_unavailable: PostgreSQL or the configured Reader is unavailable. |
|---|
504 | job_query_timeout: the bounded request timed out. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.412 The revision changed: read the latest ETag, decide again, then send the new If-Match.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/jobs/{task_id}/dead-letters
Page through dead letters in the authenticated tenant
- operationId
listTenantJobDeadLetters- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：jobs.read
Parameters
listTenantJobDeadLetters Parameters| Name | In | Type | Required | Description |
|---|
task_id | path | string(uuid) | Yes | Canonical lower-case UUID of the background job. |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | Opaque, authenticated, versioned HMAC-SHA256 keyset cursor from the preceding response, bound to route scope, endpoint, task, and filters. Reuse with changed inputs or any token modification returns 400. |
|---|
Responses
listTenantJobDeadLetters Responses| Status | Description |
|---|
200 | Dead letters ordered by terminal attempt descending. Fields：data: array<DeadLetter> page: Page |
|---|
400 | job_invalid_request: invalid UUID, query input, Idempotency-Key, content type, or exact empty JSON command body. |
|---|
401 | job_authentication_required: authentication is missing or invalid. |
|---|
403 | job_permission_denied or job_scope_forbidden: permission is missing, audience is incompatible, or the caller attempted a scope override. |
|---|
404 | job_not_found: the task does not exist or is outside the authenticated tenant scope. |
|---|
408 | job_request_cancelled: the inbound request context was cancelled. |
|---|
502 | job_store_invalid_response or job_response_too_large: stored facts were invalid or the bounded response was too large. |
|---|
503 | job_store_unavailable: PostgreSQL or the configured Reader is unavailable. |
|---|
504 | job_query_timeout: the bounded request timed out. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/jobs/{task_id}/receipts
Page through immutable settlement receipts in the authenticated tenant
- operationId
listTenantJobSettlementReceipts- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：jobs.read
Parameters
listTenantJobSettlementReceipts Parameters| Name | In | Type | Required | Description |
|---|
task_id | path | string(uuid) | Yes | Canonical lower-case UUID of the background job. |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | Opaque, authenticated, versioned HMAC-SHA256 keyset cursor from the preceding response, bound to route scope, endpoint, task, and filters. Reuse with changed inputs or any token modification returns 400. |
|---|
Responses
listTenantJobSettlementReceipts Responses| Status | Description |
|---|
200 | Settlement receipts ordered by attempt descending then ordinal ascending. Fields：data: array<SettlementReceipt> page: Page |
|---|
400 | job_invalid_request: invalid UUID, query input, Idempotency-Key, content type, or exact empty JSON command body. |
|---|
401 | job_authentication_required: authentication is missing or invalid. |
|---|
403 | job_permission_denied or job_scope_forbidden: permission is missing, audience is incompatible, or the caller attempted a scope override. |
|---|
404 | job_not_found: the task does not exist or is outside the authenticated tenant scope. |
|---|
408 | job_request_cancelled: the inbound request context was cancelled. |
|---|
502 | job_store_invalid_response or job_response_too_large: stored facts were invalid or the bounded response was too large. |
|---|
503 | job_store_unavailable: PostgreSQL or the configured Reader is unavailable. |
|---|
504 | job_query_timeout: the bounded request timed out. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/jobs/{task_id}/results
Page through current per-item and per-node result projections
- operationId
listTenantJobResults- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：jobs.read
Description (from the contract)
node_id, failure_code, and completed_at are omitted when the underlying projection has no corresponding fact. No task payload is returned.
Parameters
listTenantJobResults Parameters| Name | In | Type | Required | Description |
|---|
task_id | path | string(uuid) | Yes | Canonical lower-case UUID of the background job. |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | Opaque, authenticated, versioned HMAC-SHA256 keyset cursor from the preceding response, bound to route scope, endpoint, task, and filters. Reuse with changed inputs or any token modification returns 400. |
|---|
Responses
listTenantJobResults Responses| Status | Description |
|---|
200 | Current item projections ordered by immutable ordinal ascending. Fields：data: array<ItemResult> page: Page |
|---|
400 | job_invalid_request: invalid UUID, query input, Idempotency-Key, content type, or exact empty JSON command body. |
|---|
401 | job_authentication_required: authentication is missing or invalid. |
|---|
403 | job_permission_denied or job_scope_forbidden: permission is missing, audience is incompatible, or the caller attempted a scope override. |
|---|
404 | job_not_found: the task does not exist or is outside the authenticated tenant scope. |
|---|
408 | job_request_cancelled: the inbound request context was cancelled. |
|---|
502 | job_store_invalid_response or job_response_too_large: stored facts were invalid or the bounded response was too large. |
|---|
503 | job_store_unavailable: PostgreSQL or the configured Reader is unavailable. |
|---|
504 | job_query_timeout: the bounded request timed out. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/jobs/{task_id}/retry
Retry failed items in a tenant job
- operationId
retryTenantJob- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：jobs.manage
Description (from the contract)
Requires jobs.manage, a failed or partially failed state, and an available attempt. The transition, audit, and receipt commit atomically. The same actor and Idempotency-Key return the immutable first successful snapshot with replayed=true; reuse for another command returns 409.
Parameters
retryTenantJob Parameters| Name | In | Type | Required | Description |
|---|
task_id | path | string(uuid) | Yes | Canonical lower-case UUID of the background job. |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
If-Match | header | string | Yes | Strong ETag value returned by the latest job detail or command response. |
|---|
Request body
application/json · Required：Yes
Responses
retryTenantJob Responses| Status | Description |
|---|
200 | Immutable cancelled or queued command result snapshot. Fields：data: Job replayed: boolean |
|---|
400 | job_invalid_request: invalid UUID, query input, Idempotency-Key, content type, or exact empty JSON command body. |
|---|
401 | job_authentication_required: authentication is missing or invalid. |
|---|
403 | job_permission_denied or job_scope_forbidden: permission is missing, audience is incompatible, or the caller attempted a scope override. |
|---|
404 | job_not_found: the task does not exist or is outside the authenticated tenant scope. |
|---|
408 | job_request_cancelled: the inbound request context was cancelled. |
|---|
409 | job_idempotency_conflict, job_invalid_transition, job_retries_exhausted, or job_producer_command_required: the key was reused for another command, the job changed or is ineligible, no retry attempt remains, or the job's producer owns the command. cache.operation cancel/retry is executed by the cache module (same audit and receipt as the cache operation API); job_producer_command_required is returned only for its replay, or when cache control is not enabled. |
|---|
412 | job_revision_conflict: the If-Match revision is stale; refresh the job before retrying. |
|---|
502 | job_store_invalid_response or job_response_too_large: stored facts were invalid or the bounded response was too large. |
|---|
503 | job_store_unavailable: PostgreSQL or the configured Reader is unavailable. |
|---|
504 | job_query_timeout: the bounded request timed out. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.412 The revision changed: read the latest ETag, decide again, then send the new If-Match.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list