Jobs
Observe or cancel image, Action, and video jobs and download completed video output.
Base URL: https://app.gavana.ai/api/canvas-agent/v1 · Authentication: HTTP bearer, token format cba_<token-id>.<secret>
Operations
| Operation | Purpose | Scopes |
|---|---|---|
GET /jobs/{jobId} | Read or finalize an image, Action, or video job | job:manage |
DELETE /jobs/{jobId} | Cancel an image, Action, or video job | job:manage |
GET /jobs/{jobId}/output | Download completed video output | job:manage |
GET /jobs/{jobId}
Read or finalize an image, Action, or video job
- Operation id:
getJob - Scopes: Requires
job:manage. - CLI equivalent:
gavana job get
Parameters
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
jobId | path | string | Yes | Pattern ^(?:job:)?[0-9a-fA-F-]{36}$. |
Responses
| Status | Payload | Meaning |
|---|---|---|
200 | ImageJob | VideoJob | An image, Action, or video job state or finalized result. Image and Action results follow the documented Run retention policy. Video records are retained for 30 days and expose a protected download URL after completion. |
202 | ImageJob | VideoJob | An image, Action, or video job state or finalized result. Image and Action results follow the documented Run retention policy. Video records are retained for 30 days and expose a protected download URL after completion. |
default | ErrorResponse | A stable machine-readable error. The response always includes X-Request-ID. |
200 response body
| Field | Type | Required | Notes |
|---|---|---|---|
(ImageJob).id | string | Yes | Pattern ^job:. |
(ImageJob).run | string | Yes | Pattern ^run:. |
(ImageJob).kind | string | Yes | One of image, action. |
(ImageJob).pollUrl | string | Yes | Pattern ^/api/canvas-agent/v1/runs/. |
(ImageJob).rawId | string (uuid) | No | — |
(ImageJob).status | string | Yes | Current temporary job state. Successful results retain the observation record for 24 hours before the first successful server finalization and 15 minutes after it; an authenticated Run GET or pre-callback worker finalization both count. Failed and canceled records keep the normal 24-hour window. Expired tombstones remain seven days. One of preparing, queued, running, finalizing, canceling, succeeded, failed, canceled, expired. |
(ImageJob).estimatedSeconds | integer | No | Typical provider runtime for the selected model. This is guidance, not a deadline. min 1. |
(ImageJob).durationMs | integer | No | Total observed duration once the job is terminal. min 0. |
(ImageJob).timing | ImageJobTiming | No | — |
(ImageJob).timing.createdAt | string (date-time) | No | — |
(ImageJob).timing.queuedAt | string (date-time) | No | — |
(ImageJob).timing.startedAt | string (date-time) | No | — |
(ImageJob).timing.completedAt | string (date-time) | No | — |
(ImageJob).timing.queueDurationMs | integer | No | min 0. |
(ImageJob).timing.executionDurationMs | integer | No | min 0. |
(ImageJob).timing.totalDurationMs | integer | No | min 0. |
(ImageJob).failure | ImageJobFailure | No | — |
(ImageJob).failure.code | string | Yes | One of provider_authentication_failed, provider_timeout, provider_rate_limited, provider_rejected, provider_unavailable, runtime_failed, action_input_invalid, result_expired. |
(ImageJob).failure.message | string | Yes | — |
(ImageJob).failure.retryable | boolean | Yes | — |
(ImageJob).failure.providerStatus | integer | No | min 400, max 599. |
(ImageJob).webhook | ImageJobWebhookDelivery | No | Durable delivery state. Gavana makes four total attempts. Retryable network failures and 408, 425, 429, or 5xx responses back off for 10 seconds, 60 seconds, then 5 minutes; redirects and other 4xx responses stop delivery. |
(ImageJob).webhook.id | string | Yes | Pattern ^webhook:. |
(ImageJob).webhook.status | string | Yes | One of pending, delivering, delivered, failed. |
(ImageJob).webhook.attempts | integer | Yes | min 0. |
(ImageJob).webhook.nextAttemptAt | string (date-time) | No | — |
(ImageJob).webhook.lastAttemptAt | string (date-time) | No | — |
(ImageJob).webhook.deliveredAt | string (date-time) | No | — |
(ImageJob).webhook.lastStatus | integer | No | min 100, max 599. |
(ImageJob).webhook.errorCode | string | No | One of invalid_destination, delivery_failed, redirect_not_allowed, endpoint_rejected, secret_unavailable, finalization_unavailable, finalization_auth_unavailable, finalization_auth_expired, finalization_failed. |
(ImageJob).replayed | boolean | No | — |
(ImageJob).operation | string | No | One of generate, edit, variations, action. |
(ImageJob).actionId | string | No | Pattern ^action:. |
(ImageJob).actionVersion | string | No | — |
(ImageJob).canvasId | string | No | Pattern ^canvas:. |
(ImageJob).canvasRevision | string | No | — |
(ImageJob).canvasUrl | string (uri) | No | — |
(ImageJob).canceledAt | string (date-time) | No | — |
(ImageJob).cancelReason | string | No | One of stale_preparing, user_requested, setup_failed. |
(ImageJob).targets | array of string | No | — |
(ImageJob).references | array of string | No | — |
(ImageJob).referenceInputs | array of ImageReferenceInput | No | Exact reference handles and optional semantic roles used by the provider request. |
(ImageJob).referenceInputs[].handle | string | Yes | Pattern ^(?:node:[A-Za-z0-9_-]{1,180}|asset:(?:[A-Za-z0-9_-]{1,180}:)?[A-Za-z0-9_-]{1,180})$. |
(ImageJob).referenceInputs[].role | string | No | One of identity, construction, texture, fit, style. |
(ImageJob).images | array of ImageJobResultImage | No | — |
(ImageJob).images[].assetId | string | Yes | Pattern ^asset:. |
(ImageJob).images[].nodeId | string | Yes | Pattern ^node:. |
(ImageJob).images[].mediaType | string | No | Pattern ^image/. |
(ImageJob).images[].width | integer | No | min 1. |
(ImageJob).images[].height | integer | No | min 1. |
(ImageJob).images[].bytes | integer | No | min 1. |
(ImageJob).images[].previewUrl | string (uri) | Yes | — |
(ImageJob).images[].markdown | string | No | — |
(ImageJob).completionReview | CanvasCompletionReview | No | — |
(ImageJob).completionReview.status | string | Yes | One of ready, needs-review, blocked. |
(ImageJob).completionReview.doneClaimAllowed | boolean | Yes | False while agent-owned spatial or lineage findings remain, or a generated output is pending, failed, or non-durable. |
(ImageJob).completionReview.instruction | string | Yes | — |
(ImageJob).completionReview.outputs | CanvasCompletionOutputs | Yes | Generated-output count and durable, pending, and failed breakdown. |
(ImageJob).completionReview.outputs.count | integer | Yes | min 0. |
(ImageJob).completionReview.outputs.durableCount | integer | Yes | min 0. |
(ImageJob).completionReview.outputs.pendingCount | integer | Yes | min 0. |
(ImageJob).completionReview.outputs.failedCount | integer | Yes | min 0. |
(ImageJob).completionReview.outputs.handles | array of string | Yes | — |
(ImageJob).completionReview.overlap | CanvasCompletionFindingArea | Yes | — |
(ImageJob).completionReview.overlap.status | string | Yes | One of clear, needs-review, blocked. |
(ImageJob).completionReview.overlap.findingCodes | array of string | Yes | — |
(ImageJob).completionReview.overlap.nodeHandles | array of string | Yes | — |
(ImageJob).completionReview.overlap.connectionHandles | array of string | Yes | — |
(ImageJob).completionReview.containment | CanvasCompletionFindingArea | Yes | — |
(ImageJob).completionReview.containment.status | string | Yes | One of clear, needs-review, blocked. |
(ImageJob).completionReview.containment.findingCodes | array of string | Yes | — |
(ImageJob).completionReview.containment.nodeHandles | array of string | Yes | — |
(ImageJob).completionReview.containment.connectionHandles | array of string | Yes | — |
(ImageJob).completionReview.referenceLineage | CanvasCompletionFindingArea | Yes | — |
(ImageJob).completionReview.referenceLineage.status | string | Yes | One of clear, needs-review, blocked. |
(ImageJob).completionReview.referenceLineage.findingCodes | array of string | Yes | — |
(ImageJob).completionReview.referenceLineage.nodeHandles | array of string | Yes | — |
(ImageJob).completionReview.referenceLineage.connectionHandles | array of string | Yes | — |
(ImageJob).completionReview.productFidelity | CanvasProductFidelityReview | Yes | A conservative review signal, not an authoritative visual inspection. |
(ImageJob).completionReview.productFidelity.status | string | Yes | One of not-applicable, needs-review, passed. |
(ImageJob).completionReview.productFidelity.reviewedOutputCount | integer | Yes | min 0. |
(ImageJob).completionReview.productFidelity.needsReviewOutputHandles | array of string | Yes | — |
(ImageJob).completionReview.productFidelity.evidenceMissingOutputHandles | array of string | Yes | — |
(ImageJob).completionReview.productFidelity.reasons | array of object | No | — |
(ImageJob).completionReview.productFidelity.reasons[].nodeHandle | string | Yes | Pattern ^node:. |
(ImageJob).completionReview.productFidelity.reasons[].reason | string | Yes | — |
(ImageJob).completionReview.delivery | CanvasCompletionDelivery | Yes | Generated-output delivery evidence. A blocked state prevents a Done claim. |
(ImageJob).completionReview.delivery.status | string | Yes | One of clear, blocked. |
(ImageJob).completionReview.delivery.reasons | array of string | No | — |
(ImageJob).completionReview.delivery.pendingOutputHandles | array of string | Yes | — |
(ImageJob).completionReview.delivery.failedOutputHandles | array of string | Yes | — |
(ImageJob).completionReview.delivery.nonDurableOutputHandles | array of string | Yes | — |
(ImageJob).completionReview.blockingFindingCodes | array of string | Yes | — |
(ImageJob).completionReview.advisoryFindingCodes | array of string | Yes | — |
(VideoJob).id | string | Yes | Pattern ^job:. |
(VideoJob).rawId | string (uuid) | Yes | — |
(VideoJob).kind | “video” | Yes | — |
(VideoJob).operation | “generate” | Yes | — |
(VideoJob).pollUrl | string | Yes | Pattern ^/api/canvas-agent/v1/jobs/. |
(VideoJob).status | string | Yes | One of queued, running, succeeded, failed, canceled. |
(VideoJob).model | object | Yes | — |
(VideoJob).model.id | string | Yes | — |
(VideoJob).model.name | string | Yes | — |
(VideoJob).progress | number | Yes | min 0, max 100. |
(VideoJob).estimatedSeconds | integer | Yes | min 1. |
(VideoJob).providerRunId | string | No | — |
(VideoJob).failure | VideoJobFailure | No | — |
(VideoJob).failure.code | string | Yes | One of video_generation_failed, canceled. |
(VideoJob).failure.message | string | Yes | — |
(VideoJob).failure.retryable | boolean | Yes | — |
(VideoJob).video | object | No | — |
(VideoJob).video.downloadUrl | string | Yes | Pattern ^/api/canvas-agent/v1/jobs/.+/output$. |
(VideoJob).replayed | boolean | No | — |
(VideoJob).createdAt | string (date-time) | Yes | — |
(VideoJob).updatedAt | string (date-time) | Yes | — |
Example
curl "https://app.gavana.ai/api/canvas-agent/v1/jobs/job:0f9c1a2b-3d4e-4f50-8a61-7b2c3d4e5f60" \
-H "Authorization: Bearer $GAVANA_AGENT_TOKEN"DELETE /jobs/{jobId}
Cancel an image, Action, or video job
- Operation id:
cancelJob - Scopes: Requires
job:manage. - CLI equivalent:
gavana job cancel
Parameters
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
jobId | path | string | Yes | Pattern ^(?:job:)?[0-9a-fA-F-]{36}$. |
Responses
| Status | Payload | Meaning |
|---|---|---|
200 | ImageJob | VideoJob | An image, Action, or video job state or finalized result. Image and Action results follow the documented Run retention policy. Video records are retained for 30 days and expose a protected download URL after completion. |
202 | ImageJob | VideoJob | An image, Action, or video job state or finalized result. Image and Action results follow the documented Run retention policy. Video records are retained for 30 days and expose a protected download URL after completion. |
default | ErrorResponse | A stable machine-readable error. The response always includes X-Request-ID. |
200 response body
| Field | Type | Required | Notes |
|---|---|---|---|
(ImageJob).id | string | Yes | Pattern ^job:. |
(ImageJob).run | string | Yes | Pattern ^run:. |
(ImageJob).kind | string | Yes | One of image, action. |
(ImageJob).pollUrl | string | Yes | Pattern ^/api/canvas-agent/v1/runs/. |
(ImageJob).rawId | string (uuid) | No | — |
(ImageJob).status | string | Yes | Current temporary job state. Successful results retain the observation record for 24 hours before the first successful server finalization and 15 minutes after it; an authenticated Run GET or pre-callback worker finalization both count. Failed and canceled records keep the normal 24-hour window. Expired tombstones remain seven days. One of preparing, queued, running, finalizing, canceling, succeeded, failed, canceled, expired. |
(ImageJob).estimatedSeconds | integer | No | Typical provider runtime for the selected model. This is guidance, not a deadline. min 1. |
(ImageJob).durationMs | integer | No | Total observed duration once the job is terminal. min 0. |
(ImageJob).timing | ImageJobTiming | No | — |
(ImageJob).timing.createdAt | string (date-time) | No | — |
(ImageJob).timing.queuedAt | string (date-time) | No | — |
(ImageJob).timing.startedAt | string (date-time) | No | — |
(ImageJob).timing.completedAt | string (date-time) | No | — |
(ImageJob).timing.queueDurationMs | integer | No | min 0. |
(ImageJob).timing.executionDurationMs | integer | No | min 0. |
(ImageJob).timing.totalDurationMs | integer | No | min 0. |
(ImageJob).failure | ImageJobFailure | No | — |
(ImageJob).failure.code | string | Yes | One of provider_authentication_failed, provider_timeout, provider_rate_limited, provider_rejected, provider_unavailable, runtime_failed, action_input_invalid, result_expired. |
(ImageJob).failure.message | string | Yes | — |
(ImageJob).failure.retryable | boolean | Yes | — |
(ImageJob).failure.providerStatus | integer | No | min 400, max 599. |
(ImageJob).webhook | ImageJobWebhookDelivery | No | Durable delivery state. Gavana makes four total attempts. Retryable network failures and 408, 425, 429, or 5xx responses back off for 10 seconds, 60 seconds, then 5 minutes; redirects and other 4xx responses stop delivery. |
(ImageJob).webhook.id | string | Yes | Pattern ^webhook:. |
(ImageJob).webhook.status | string | Yes | One of pending, delivering, delivered, failed. |
(ImageJob).webhook.attempts | integer | Yes | min 0. |
(ImageJob).webhook.nextAttemptAt | string (date-time) | No | — |
(ImageJob).webhook.lastAttemptAt | string (date-time) | No | — |
(ImageJob).webhook.deliveredAt | string (date-time) | No | — |
(ImageJob).webhook.lastStatus | integer | No | min 100, max 599. |
(ImageJob).webhook.errorCode | string | No | One of invalid_destination, delivery_failed, redirect_not_allowed, endpoint_rejected, secret_unavailable, finalization_unavailable, finalization_auth_unavailable, finalization_auth_expired, finalization_failed. |
(ImageJob).replayed | boolean | No | — |
(ImageJob).operation | string | No | One of generate, edit, variations, action. |
(ImageJob).actionId | string | No | Pattern ^action:. |
(ImageJob).actionVersion | string | No | — |
(ImageJob).canvasId | string | No | Pattern ^canvas:. |
(ImageJob).canvasRevision | string | No | — |
(ImageJob).canvasUrl | string (uri) | No | — |
(ImageJob).canceledAt | string (date-time) | No | — |
(ImageJob).cancelReason | string | No | One of stale_preparing, user_requested, setup_failed. |
(ImageJob).targets | array of string | No | — |
(ImageJob).references | array of string | No | — |
(ImageJob).referenceInputs | array of ImageReferenceInput | No | Exact reference handles and optional semantic roles used by the provider request. |
(ImageJob).referenceInputs[].handle | string | Yes | Pattern ^(?:node:[A-Za-z0-9_-]{1,180}|asset:(?:[A-Za-z0-9_-]{1,180}:)?[A-Za-z0-9_-]{1,180})$. |
(ImageJob).referenceInputs[].role | string | No | One of identity, construction, texture, fit, style. |
(ImageJob).images | array of ImageJobResultImage | No | — |
(ImageJob).images[].assetId | string | Yes | Pattern ^asset:. |
(ImageJob).images[].nodeId | string | Yes | Pattern ^node:. |
(ImageJob).images[].mediaType | string | No | Pattern ^image/. |
(ImageJob).images[].width | integer | No | min 1. |
(ImageJob).images[].height | integer | No | min 1. |
(ImageJob).images[].bytes | integer | No | min 1. |
(ImageJob).images[].previewUrl | string (uri) | Yes | — |
(ImageJob).images[].markdown | string | No | — |
(ImageJob).completionReview | CanvasCompletionReview | No | — |
(ImageJob).completionReview.status | string | Yes | One of ready, needs-review, blocked. |
(ImageJob).completionReview.doneClaimAllowed | boolean | Yes | False while agent-owned spatial or lineage findings remain, or a generated output is pending, failed, or non-durable. |
(ImageJob).completionReview.instruction | string | Yes | — |
(ImageJob).completionReview.outputs | CanvasCompletionOutputs | Yes | Generated-output count and durable, pending, and failed breakdown. |
(ImageJob).completionReview.outputs.count | integer | Yes | min 0. |
(ImageJob).completionReview.outputs.durableCount | integer | Yes | min 0. |
(ImageJob).completionReview.outputs.pendingCount | integer | Yes | min 0. |
(ImageJob).completionReview.outputs.failedCount | integer | Yes | min 0. |
(ImageJob).completionReview.outputs.handles | array of string | Yes | — |
(ImageJob).completionReview.overlap | CanvasCompletionFindingArea | Yes | — |
(ImageJob).completionReview.overlap.status | string | Yes | One of clear, needs-review, blocked. |
(ImageJob).completionReview.overlap.findingCodes | array of string | Yes | — |
(ImageJob).completionReview.overlap.nodeHandles | array of string | Yes | — |
(ImageJob).completionReview.overlap.connectionHandles | array of string | Yes | — |
(ImageJob).completionReview.containment | CanvasCompletionFindingArea | Yes | — |
(ImageJob).completionReview.containment.status | string | Yes | One of clear, needs-review, blocked. |
(ImageJob).completionReview.containment.findingCodes | array of string | Yes | — |
(ImageJob).completionReview.containment.nodeHandles | array of string | Yes | — |
(ImageJob).completionReview.containment.connectionHandles | array of string | Yes | — |
(ImageJob).completionReview.referenceLineage | CanvasCompletionFindingArea | Yes | — |
(ImageJob).completionReview.referenceLineage.status | string | Yes | One of clear, needs-review, blocked. |
(ImageJob).completionReview.referenceLineage.findingCodes | array of string | Yes | — |
(ImageJob).completionReview.referenceLineage.nodeHandles | array of string | Yes | — |
(ImageJob).completionReview.referenceLineage.connectionHandles | array of string | Yes | — |
(ImageJob).completionReview.productFidelity | CanvasProductFidelityReview | Yes | A conservative review signal, not an authoritative visual inspection. |
(ImageJob).completionReview.productFidelity.status | string | Yes | One of not-applicable, needs-review, passed. |
(ImageJob).completionReview.productFidelity.reviewedOutputCount | integer | Yes | min 0. |
(ImageJob).completionReview.productFidelity.needsReviewOutputHandles | array of string | Yes | — |
(ImageJob).completionReview.productFidelity.evidenceMissingOutputHandles | array of string | Yes | — |
(ImageJob).completionReview.productFidelity.reasons | array of object | No | — |
(ImageJob).completionReview.productFidelity.reasons[].nodeHandle | string | Yes | Pattern ^node:. |
(ImageJob).completionReview.productFidelity.reasons[].reason | string | Yes | — |
(ImageJob).completionReview.delivery | CanvasCompletionDelivery | Yes | Generated-output delivery evidence. A blocked state prevents a Done claim. |
(ImageJob).completionReview.delivery.status | string | Yes | One of clear, blocked. |
(ImageJob).completionReview.delivery.reasons | array of string | No | — |
(ImageJob).completionReview.delivery.pendingOutputHandles | array of string | Yes | — |
(ImageJob).completionReview.delivery.failedOutputHandles | array of string | Yes | — |
(ImageJob).completionReview.delivery.nonDurableOutputHandles | array of string | Yes | — |
(ImageJob).completionReview.blockingFindingCodes | array of string | Yes | — |
(ImageJob).completionReview.advisoryFindingCodes | array of string | Yes | — |
(VideoJob).id | string | Yes | Pattern ^job:. |
(VideoJob).rawId | string (uuid) | Yes | — |
(VideoJob).kind | “video” | Yes | — |
(VideoJob).operation | “generate” | Yes | — |
(VideoJob).pollUrl | string | Yes | Pattern ^/api/canvas-agent/v1/jobs/. |
(VideoJob).status | string | Yes | One of queued, running, succeeded, failed, canceled. |
(VideoJob).model | object | Yes | — |
(VideoJob).model.id | string | Yes | — |
(VideoJob).model.name | string | Yes | — |
(VideoJob).progress | number | Yes | min 0, max 100. |
(VideoJob).estimatedSeconds | integer | Yes | min 1. |
(VideoJob).providerRunId | string | No | — |
(VideoJob).failure | VideoJobFailure | No | — |
(VideoJob).failure.code | string | Yes | One of video_generation_failed, canceled. |
(VideoJob).failure.message | string | Yes | — |
(VideoJob).failure.retryable | boolean | Yes | — |
(VideoJob).video | object | No | — |
(VideoJob).video.downloadUrl | string | Yes | Pattern ^/api/canvas-agent/v1/jobs/.+/output$. |
(VideoJob).replayed | boolean | No | — |
(VideoJob).createdAt | string (date-time) | Yes | — |
(VideoJob).updatedAt | string (date-time) | Yes | — |
Example
curl -X DELETE "https://app.gavana.ai/api/canvas-agent/v1/jobs/job:0f9c1a2b-3d4e-4f50-8a61-7b2c3d4e5f60" \
-H "Authorization: Bearer $GAVANA_AGENT_TOKEN"GET /jobs/{jobId}/output
Download completed video output
- Operation id:
downloadVideoJobOutput - Scopes: Requires
job:manage. - CLI equivalent:
gavana video download
Parameters
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
jobId | path | string | Yes | Pattern ^(?:job:)?[0-9a-fA-F-]{36}$. |
Responses
| Status | Payload | Meaning |
|---|---|---|
200 | video/mp4 | The generated video stream. The concrete Content-Type is the provider result, such as video/mp4 or video/webm. |
default | ErrorResponse | A stable machine-readable error. The response always includes X-Request-ID. |
Example
curl "https://app.gavana.ai/api/canvas-agent/v1/jobs/job:0f9c1a2b-3d4e-4f50-8a61-7b2c3d4e5f60/output" \
-H "Authorization: Bearer $GAVANA_AGENT_TOKEN"Errors
Every failure uses the shared error envelope described in Errors and X-Request-ID. The response always carries X-Request-ID; share that value with support instead of the request payload.
Last updated on