接口详情
GET /v1/jobs
Page through jobs in the authenticated tenant scope
- operationId
listTenantJobs- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：jobs.read
说明（契约原文）
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.
参数
listTenantJobs 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
from | query | string(date-time) | 是 | Inclusive RFC3339 creation-time bound. |
|---|
to | query | string(date-time) | 是 | Exclusive RFC3339 creation-time bound; from-to may not exceed 31 days. |
|---|
status | query | array<string: queued / running / succeeded / partial_failed / failed / cancelled> | 否 | Comma-separated job states; duplicates are rejected. |
|---|
task_id | query | string(uuid) | 否 | Exact task UUID filter. |
|---|
kind | query | string | 否 | — |
|---|
resource | query | string | 否 | 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 | 否 | — |
|---|
cursor | query | string | 否 | 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 | 否 | 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. |
|---|
响应
listTenantJobs 响应| 状态码 | 说明 |
|---|
200 | Authenticated keyset page or explicit numbered page with a same-snapshot exact total. 字段：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. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/jobs/kinds
Read the integrated producer catalog as a tenant
- operationId
listTenantJobKinds- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：jobs.read
说明（契约原文）
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.
响应
listTenantJobKinds 响应| 状态码 | 说明 |
|---|
200 | Registered source-backed producer kinds, independent of current job rows or runtime enablement. 字段：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. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
↑ 回到列表
GET /v1/jobs/{task_id}
Read a job in the authenticated tenant scope
- operationId
getTenantJob- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：jobs.read
说明（契约原文）
A missing or cross-tenant task_id returns the same 404 response.
参数
getTenantJob 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
task_id | path | string(uuid) | 是 | Canonical lower-case UUID of the background job. |
|---|
响应
getTenantJob 响应| 状态码 | 说明 |
|---|
200 | Job projection without producer payload or credentials. 字段：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. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/jobs/{task_id}/attempts
Page through a tenant job's immutable attempt history
- operationId
listTenantJobAttempts- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：jobs.read
参数
listTenantJobAttempts 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
task_id | path | string(uuid) | 是 | Canonical lower-case UUID of the background job. |
|---|
limit | query | integer | 否 | — |
|---|
cursor | query | string | 否 | 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. |
|---|
响应
listTenantJobAttempts 响应| 状态码 | 说明 |
|---|
200 | Attempt history ordered by attempt number descending. 字段：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. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/jobs/{task_id}/cancel
Cancel a queued or running job in the authenticated tenant
- operationId
cancelTenantJob- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：jobs.manage
说明（契约原文）
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.
参数
cancelTenantJob 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
task_id | path | string(uuid) | 是 | Canonical lower-case UUID of the background job. |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
If-Match | header | string | 是 | Strong ETag value returned by the latest job detail or command response. |
|---|
请求体
application/json · 必填：是
响应
cancelTenantJob 响应| 状态码 | 说明 |
|---|
200 | Immutable cancelled or queued command result snapshot. 字段：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. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/jobs/{task_id}/dead-letters
Page through dead letters in the authenticated tenant
- operationId
listTenantJobDeadLetters- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：jobs.read
参数
listTenantJobDeadLetters 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
task_id | path | string(uuid) | 是 | Canonical lower-case UUID of the background job. |
|---|
limit | query | integer | 否 | — |
|---|
cursor | query | string | 否 | 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. |
|---|
响应
listTenantJobDeadLetters 响应| 状态码 | 说明 |
|---|
200 | Dead letters ordered by terminal attempt descending. 字段：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. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/jobs/{task_id}/receipts
Page through immutable settlement receipts in the authenticated tenant
- operationId
listTenantJobSettlementReceipts- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：jobs.read
参数
listTenantJobSettlementReceipts 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
task_id | path | string(uuid) | 是 | Canonical lower-case UUID of the background job. |
|---|
limit | query | integer | 否 | — |
|---|
cursor | query | string | 否 | 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. |
|---|
响应
listTenantJobSettlementReceipts 响应| 状态码 | 说明 |
|---|
200 | Settlement receipts ordered by attempt descending then ordinal ascending. 字段：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. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/jobs/{task_id}/results
Page through current per-item and per-node result projections
- operationId
listTenantJobResults- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：jobs.read
说明（契约原文）
node_id, failure_code, and completed_at are omitted when the underlying projection has no corresponding fact. No task payload is returned.
参数
listTenantJobResults 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
task_id | path | string(uuid) | 是 | Canonical lower-case UUID of the background job. |
|---|
limit | query | integer | 否 | — |
|---|
cursor | query | string | 否 | 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. |
|---|
响应
listTenantJobResults 响应| 状态码 | 说明 |
|---|
200 | Current item projections ordered by immutable ordinal ascending. 字段：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. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/jobs/{task_id}/retry
Retry failed items in a tenant job
- operationId
retryTenantJob- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：jobs.manage
说明（契约原文）
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.
参数
retryTenantJob 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
task_id | path | string(uuid) | 是 | Canonical lower-case UUID of the background job. |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
If-Match | header | string | 是 | Strong ETag value returned by the latest job detail or command response. |
|---|
请求体
application/json · 必填：是
响应
retryTenantJob 响应| 状态码 | 说明 |
|---|
200 | Immutable cancelled or queued command result snapshot. 字段：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. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表