Runs
Read, resume, or cancel Recipe, image, and Action execution through one shared resource.
Base URL: https://app.gavana.ai/api/canvas-agent/v1 · Authentication: HTTP bearer, token format cba_<token-id>.<secret>
Operations
| Operation | Purpose | Scopes |
|---|---|---|
GET /runs/{runId} | Read or advance a shared Run | job:manage |
DELETE /runs/{runId} | Cancel a shared Run | job:manage |
GET /runs/{runId}
Read or advance a shared Run
Returns Recipe, image, or Action Run state. Reading a completed image child also finalizes its durable asset and canvas node.
- Operation id:
getRun - Scopes: Requires
job:manage. - CLI equivalent:
gavana run get
Parameters
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
runId | path | string | Yes | Pattern ^(?:run:)?[A-Za-z0-9_-]{1,180}$. |
Responses
| Status | Payload | Meaning |
|---|---|---|
200 | Run | A shared Recipe, image, or Action Run. |
202 | Run | A shared Recipe, image, or Action Run. |
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 | — |
(RecipeRun).schemaVersion | 1 | Yes | — |
(RecipeRun).id | string | Yes | Pattern ^recipe-. |
(RecipeRun).rawId | string | Yes | Pattern ^recipe-. |
(RecipeRun).handle | string | Yes | Pattern ^run:recipe-. |
(RecipeRun).run | string | Yes | Pattern ^run:recipe-. |
(RecipeRun).kind | “recipe” | Yes | — |
(RecipeRun).operation | “recipe” | Yes | — |
(RecipeRun).status | string | Yes | One of queued, running, succeeded, failed, canceled. |
(RecipeRun).recipeId | string | Yes | Pattern ^[A-Za-z0-9_-]{1,180}$. |
(RecipeRun).recipeHandle | string | Yes | Pattern ^recipe:. |
(RecipeRun).recipeVersion | string | Yes | — |
(RecipeRun).recipeInstanceNodeId | string | Yes | Pattern ^[A-Za-z0-9_-]{1,180}$. |
(RecipeRun).recipeInstanceNodeHandle | string | Yes | Pattern ^node:. |
(RecipeRun).canvasId | string | Yes | Pattern ^[A-Za-z0-9_-]{1,180}$. |
(RecipeRun).canvasHandle | string | Yes | Pattern ^canvas:. |
(RecipeRun).canvasUrl | string (uri) | No | — |
(RecipeRun).inputs | array of RecipeRunInputBinding | Yes | — |
(RecipeRun).inputs[].key | string | Yes | — |
(RecipeRun).inputs[].label | string | Yes | — |
(RecipeRun).inputs[].type | string | Yes | One of image, text, sticky. |
(RecipeRun).inputs[].nodeId | string | Yes | Pattern ^[A-Za-z0-9_-]{1,180}$. |
(RecipeRun).inputs[].nodeHandle | string | Yes | Pattern ^node:. |
(RecipeRun).inputs[].sourceHandle | string | No | Pattern ^(?:node|asset):. |
(RecipeRun).inputs[].summary | string | Yes | — |
(RecipeRun).outputs | array of RecipeRunOutput | Yes | — |
(RecipeRun).outputs[].key | string | Yes | — |
(RecipeRun).outputs[].label | string | Yes | — |
(RecipeRun).outputs[].type | string | Yes | One of image, text, sticky. |
(RecipeRun).outputs[].status | string | Yes | One of pending, running, succeeded, failed, canceled. |
(RecipeRun).outputs[].nodeId | string | Yes | Pattern ^[A-Za-z0-9_-]{1,180}$. |
(RecipeRun).outputs[].nodeHandle | string | Yes | Pattern ^node:. |
(RecipeRun).outputs[].jobId | string (uuid) | No | — |
(RecipeRun).outputs[].runHandle | string | No | Pattern ^run:. |
(RecipeRun).outputs[].assetId | string | No | Pattern ^asset:. |
(RecipeRun).outputs[].value | string | No | max length 24000. |
(RecipeRun).outputs[].startedAt | string (date-time) | No | — |
(RecipeRun).outputs[].completedAt | string (date-time) | No | — |
(RecipeRun).outputs[].failure | RecipeRunFailure | No | — |
(RecipeRun).outputs[].failure.code | string | Yes | One of recipe_input_invalid, recipe_step_failed, recipe_output_missing, recipe_run_canceled, delegation_revoked. |
(RecipeRun).outputs[].failure.message | string | Yes | — |
(RecipeRun).outputs[].failure.retryable | boolean | Yes | — |
(RecipeRun).outputs[].failure.outputKey | string | No | — |
(RecipeRun).targets | array of string | Yes | — |
(RecipeRun).currentStep | string | Yes | — |
(RecipeRun).nextStep | string | No | — |
(RecipeRun).estimatedSeconds | integer | Yes | min 1. |
(RecipeRun).durationMs | integer | No | min 0. |
(RecipeRun).timing | ImageJobTiming | Yes | — |
(RecipeRun).timing.createdAt | string (date-time) | No | — |
(RecipeRun).timing.queuedAt | string (date-time) | No | — |
(RecipeRun).timing.startedAt | string (date-time) | No | — |
(RecipeRun).timing.completedAt | string (date-time) | No | — |
(RecipeRun).timing.queueDurationMs | integer | No | min 0. |
(RecipeRun).timing.executionDurationMs | integer | No | min 0. |
(RecipeRun).timing.totalDurationMs | integer | No | min 0. |
(RecipeRun).failure | RecipeRunFailure | No | — |
(RecipeRun).failure.code | string | Yes | One of recipe_input_invalid, recipe_step_failed, recipe_output_missing, recipe_run_canceled, delegation_revoked. |
(RecipeRun).failure.message | string | Yes | — |
(RecipeRun).failure.retryable | boolean | Yes | — |
(RecipeRun).failure.outputKey | string | No | — |
(RecipeRun).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. |
(RecipeRun).webhook.id | string | Yes | Pattern ^webhook:. |
(RecipeRun).webhook.status | string | Yes | One of pending, delivering, delivered, failed. |
(RecipeRun).webhook.attempts | integer | Yes | min 0. |
(RecipeRun).webhook.nextAttemptAt | string (date-time) | No | — |
(RecipeRun).webhook.lastAttemptAt | string (date-time) | No | — |
(RecipeRun).webhook.deliveredAt | string (date-time) | No | — |
(RecipeRun).webhook.lastStatus | integer | No | min 100, max 599. |
(RecipeRun).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. |
(RecipeRun).replayed | boolean | No | — |
(RecipeRun).pollUrl | string | Yes | Pattern ^/api/canvas-agent/v1/runs/. |
(RecipeRun).createdAt | string (date-time) | Yes | — |
(RecipeRun).updatedAt | string (date-time) | Yes | — |
(RecipeRun).startedAt | string (date-time) | No | — |
(RecipeRun).completedAt | string (date-time) | No | — |
(RecipeRun).canceledAt | string (date-time) | No | — |
(RecipeRun).completionReview | CanvasCompletionReview | No | — |
(RecipeRun).completionReview.status | string | Yes | One of ready, needs-review, blocked. |
(RecipeRun).completionReview.doneClaimAllowed | boolean | Yes | False while agent-owned spatial or lineage findings remain, or a generated output is pending, failed, or non-durable. |
(RecipeRun).completionReview.instruction | string | Yes | — |
(RecipeRun).completionReview.outputs | CanvasCompletionOutputs | Yes | Generated-output count and durable, pending, and failed breakdown. |
(RecipeRun).completionReview.outputs.count | integer | Yes | min 0. |
(RecipeRun).completionReview.outputs.durableCount | integer | Yes | min 0. |
(RecipeRun).completionReview.outputs.pendingCount | integer | Yes | min 0. |
(RecipeRun).completionReview.outputs.failedCount | integer | Yes | min 0. |
(RecipeRun).completionReview.outputs.handles | array of string | Yes | — |
(RecipeRun).completionReview.overlap | CanvasCompletionFindingArea | Yes | — |
(RecipeRun).completionReview.overlap.status | string | Yes | One of clear, needs-review, blocked. |
(RecipeRun).completionReview.overlap.findingCodes | array of string | Yes | — |
(RecipeRun).completionReview.overlap.nodeHandles | array of string | Yes | — |
(RecipeRun).completionReview.overlap.connectionHandles | array of string | Yes | — |
(RecipeRun).completionReview.containment | CanvasCompletionFindingArea | Yes | — |
(RecipeRun).completionReview.containment.status | string | Yes | One of clear, needs-review, blocked. |
(RecipeRun).completionReview.containment.findingCodes | array of string | Yes | — |
(RecipeRun).completionReview.containment.nodeHandles | array of string | Yes | — |
(RecipeRun).completionReview.containment.connectionHandles | array of string | Yes | — |
(RecipeRun).completionReview.referenceLineage | CanvasCompletionFindingArea | Yes | — |
(RecipeRun).completionReview.referenceLineage.status | string | Yes | One of clear, needs-review, blocked. |
(RecipeRun).completionReview.referenceLineage.findingCodes | array of string | Yes | — |
(RecipeRun).completionReview.referenceLineage.nodeHandles | array of string | Yes | — |
(RecipeRun).completionReview.referenceLineage.connectionHandles | array of string | Yes | — |
(RecipeRun).completionReview.productFidelity | CanvasProductFidelityReview | Yes | A conservative review signal, not an authoritative visual inspection. |
(RecipeRun).completionReview.productFidelity.status | string | Yes | One of not-applicable, needs-review, passed. |
(RecipeRun).completionReview.productFidelity.reviewedOutputCount | integer | Yes | min 0. |
(RecipeRun).completionReview.productFidelity.needsReviewOutputHandles | array of string | Yes | — |
(RecipeRun).completionReview.productFidelity.evidenceMissingOutputHandles | array of string | Yes | — |
(RecipeRun).completionReview.productFidelity.reasons | array of object | No | — |
(RecipeRun).completionReview.productFidelity.reasons[].nodeHandle | string | Yes | Pattern ^node:. |
(RecipeRun).completionReview.productFidelity.reasons[].reason | string | Yes | — |
(RecipeRun).completionReview.delivery | CanvasCompletionDelivery | Yes | Generated-output delivery evidence. A blocked state prevents a Done claim. |
(RecipeRun).completionReview.delivery.status | string | Yes | One of clear, blocked. |
(RecipeRun).completionReview.delivery.reasons | array of string | No | — |
(RecipeRun).completionReview.delivery.pendingOutputHandles | array of string | Yes | — |
(RecipeRun).completionReview.delivery.failedOutputHandles | array of string | Yes | — |
(RecipeRun).completionReview.delivery.nonDurableOutputHandles | array of string | Yes | — |
(RecipeRun).completionReview.blockingFindingCodes | array of string | Yes | — |
(RecipeRun).completionReview.advisoryFindingCodes | array of string | Yes | — |
Example
curl "https://app.gavana.ai/api/canvas-agent/v1/runs/run:4c7a9e12" \
-H "Authorization: Bearer $GAVANA_AGENT_TOKEN"DELETE /runs/{runId}
Cancel a shared Run
- Operation id:
cancelRun - Scopes: Requires
job:manage. - CLI equivalent:
gavana run cancel
Parameters
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
runId | path | string | Yes | Pattern ^(?:run:)?[A-Za-z0-9_-]{1,180}$. |
Responses
| Status | Payload | Meaning |
|---|---|---|
200 | Run | A shared Recipe, image, or Action Run. |
202 | Run | A shared Recipe, image, or Action Run. |
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 | — |
(RecipeRun).schemaVersion | 1 | Yes | — |
(RecipeRun).id | string | Yes | Pattern ^recipe-. |
(RecipeRun).rawId | string | Yes | Pattern ^recipe-. |
(RecipeRun).handle | string | Yes | Pattern ^run:recipe-. |
(RecipeRun).run | string | Yes | Pattern ^run:recipe-. |
(RecipeRun).kind | “recipe” | Yes | — |
(RecipeRun).operation | “recipe” | Yes | — |
(RecipeRun).status | string | Yes | One of queued, running, succeeded, failed, canceled. |
(RecipeRun).recipeId | string | Yes | Pattern ^[A-Za-z0-9_-]{1,180}$. |
(RecipeRun).recipeHandle | string | Yes | Pattern ^recipe:. |
(RecipeRun).recipeVersion | string | Yes | — |
(RecipeRun).recipeInstanceNodeId | string | Yes | Pattern ^[A-Za-z0-9_-]{1,180}$. |
(RecipeRun).recipeInstanceNodeHandle | string | Yes | Pattern ^node:. |
(RecipeRun).canvasId | string | Yes | Pattern ^[A-Za-z0-9_-]{1,180}$. |
(RecipeRun).canvasHandle | string | Yes | Pattern ^canvas:. |
(RecipeRun).canvasUrl | string (uri) | No | — |
(RecipeRun).inputs | array of RecipeRunInputBinding | Yes | — |
(RecipeRun).inputs[].key | string | Yes | — |
(RecipeRun).inputs[].label | string | Yes | — |
(RecipeRun).inputs[].type | string | Yes | One of image, text, sticky. |
(RecipeRun).inputs[].nodeId | string | Yes | Pattern ^[A-Za-z0-9_-]{1,180}$. |
(RecipeRun).inputs[].nodeHandle | string | Yes | Pattern ^node:. |
(RecipeRun).inputs[].sourceHandle | string | No | Pattern ^(?:node|asset):. |
(RecipeRun).inputs[].summary | string | Yes | — |
(RecipeRun).outputs | array of RecipeRunOutput | Yes | — |
(RecipeRun).outputs[].key | string | Yes | — |
(RecipeRun).outputs[].label | string | Yes | — |
(RecipeRun).outputs[].type | string | Yes | One of image, text, sticky. |
(RecipeRun).outputs[].status | string | Yes | One of pending, running, succeeded, failed, canceled. |
(RecipeRun).outputs[].nodeId | string | Yes | Pattern ^[A-Za-z0-9_-]{1,180}$. |
(RecipeRun).outputs[].nodeHandle | string | Yes | Pattern ^node:. |
(RecipeRun).outputs[].jobId | string (uuid) | No | — |
(RecipeRun).outputs[].runHandle | string | No | Pattern ^run:. |
(RecipeRun).outputs[].assetId | string | No | Pattern ^asset:. |
(RecipeRun).outputs[].value | string | No | max length 24000. |
(RecipeRun).outputs[].startedAt | string (date-time) | No | — |
(RecipeRun).outputs[].completedAt | string (date-time) | No | — |
(RecipeRun).outputs[].failure | RecipeRunFailure | No | — |
(RecipeRun).outputs[].failure.code | string | Yes | One of recipe_input_invalid, recipe_step_failed, recipe_output_missing, recipe_run_canceled, delegation_revoked. |
(RecipeRun).outputs[].failure.message | string | Yes | — |
(RecipeRun).outputs[].failure.retryable | boolean | Yes | — |
(RecipeRun).outputs[].failure.outputKey | string | No | — |
(RecipeRun).targets | array of string | Yes | — |
(RecipeRun).currentStep | string | Yes | — |
(RecipeRun).nextStep | string | No | — |
(RecipeRun).estimatedSeconds | integer | Yes | min 1. |
(RecipeRun).durationMs | integer | No | min 0. |
(RecipeRun).timing | ImageJobTiming | Yes | — |
(RecipeRun).timing.createdAt | string (date-time) | No | — |
(RecipeRun).timing.queuedAt | string (date-time) | No | — |
(RecipeRun).timing.startedAt | string (date-time) | No | — |
(RecipeRun).timing.completedAt | string (date-time) | No | — |
(RecipeRun).timing.queueDurationMs | integer | No | min 0. |
(RecipeRun).timing.executionDurationMs | integer | No | min 0. |
(RecipeRun).timing.totalDurationMs | integer | No | min 0. |
(RecipeRun).failure | RecipeRunFailure | No | — |
(RecipeRun).failure.code | string | Yes | One of recipe_input_invalid, recipe_step_failed, recipe_output_missing, recipe_run_canceled, delegation_revoked. |
(RecipeRun).failure.message | string | Yes | — |
(RecipeRun).failure.retryable | boolean | Yes | — |
(RecipeRun).failure.outputKey | string | No | — |
(RecipeRun).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. |
(RecipeRun).webhook.id | string | Yes | Pattern ^webhook:. |
(RecipeRun).webhook.status | string | Yes | One of pending, delivering, delivered, failed. |
(RecipeRun).webhook.attempts | integer | Yes | min 0. |
(RecipeRun).webhook.nextAttemptAt | string (date-time) | No | — |
(RecipeRun).webhook.lastAttemptAt | string (date-time) | No | — |
(RecipeRun).webhook.deliveredAt | string (date-time) | No | — |
(RecipeRun).webhook.lastStatus | integer | No | min 100, max 599. |
(RecipeRun).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. |
(RecipeRun).replayed | boolean | No | — |
(RecipeRun).pollUrl | string | Yes | Pattern ^/api/canvas-agent/v1/runs/. |
(RecipeRun).createdAt | string (date-time) | Yes | — |
(RecipeRun).updatedAt | string (date-time) | Yes | — |
(RecipeRun).startedAt | string (date-time) | No | — |
(RecipeRun).completedAt | string (date-time) | No | — |
(RecipeRun).canceledAt | string (date-time) | No | — |
(RecipeRun).completionReview | CanvasCompletionReview | No | — |
(RecipeRun).completionReview.status | string | Yes | One of ready, needs-review, blocked. |
(RecipeRun).completionReview.doneClaimAllowed | boolean | Yes | False while agent-owned spatial or lineage findings remain, or a generated output is pending, failed, or non-durable. |
(RecipeRun).completionReview.instruction | string | Yes | — |
(RecipeRun).completionReview.outputs | CanvasCompletionOutputs | Yes | Generated-output count and durable, pending, and failed breakdown. |
(RecipeRun).completionReview.outputs.count | integer | Yes | min 0. |
(RecipeRun).completionReview.outputs.durableCount | integer | Yes | min 0. |
(RecipeRun).completionReview.outputs.pendingCount | integer | Yes | min 0. |
(RecipeRun).completionReview.outputs.failedCount | integer | Yes | min 0. |
(RecipeRun).completionReview.outputs.handles | array of string | Yes | — |
(RecipeRun).completionReview.overlap | CanvasCompletionFindingArea | Yes | — |
(RecipeRun).completionReview.overlap.status | string | Yes | One of clear, needs-review, blocked. |
(RecipeRun).completionReview.overlap.findingCodes | array of string | Yes | — |
(RecipeRun).completionReview.overlap.nodeHandles | array of string | Yes | — |
(RecipeRun).completionReview.overlap.connectionHandles | array of string | Yes | — |
(RecipeRun).completionReview.containment | CanvasCompletionFindingArea | Yes | — |
(RecipeRun).completionReview.containment.status | string | Yes | One of clear, needs-review, blocked. |
(RecipeRun).completionReview.containment.findingCodes | array of string | Yes | — |
(RecipeRun).completionReview.containment.nodeHandles | array of string | Yes | — |
(RecipeRun).completionReview.containment.connectionHandles | array of string | Yes | — |
(RecipeRun).completionReview.referenceLineage | CanvasCompletionFindingArea | Yes | — |
(RecipeRun).completionReview.referenceLineage.status | string | Yes | One of clear, needs-review, blocked. |
(RecipeRun).completionReview.referenceLineage.findingCodes | array of string | Yes | — |
(RecipeRun).completionReview.referenceLineage.nodeHandles | array of string | Yes | — |
(RecipeRun).completionReview.referenceLineage.connectionHandles | array of string | Yes | — |
(RecipeRun).completionReview.productFidelity | CanvasProductFidelityReview | Yes | A conservative review signal, not an authoritative visual inspection. |
(RecipeRun).completionReview.productFidelity.status | string | Yes | One of not-applicable, needs-review, passed. |
(RecipeRun).completionReview.productFidelity.reviewedOutputCount | integer | Yes | min 0. |
(RecipeRun).completionReview.productFidelity.needsReviewOutputHandles | array of string | Yes | — |
(RecipeRun).completionReview.productFidelity.evidenceMissingOutputHandles | array of string | Yes | — |
(RecipeRun).completionReview.productFidelity.reasons | array of object | No | — |
(RecipeRun).completionReview.productFidelity.reasons[].nodeHandle | string | Yes | Pattern ^node:. |
(RecipeRun).completionReview.productFidelity.reasons[].reason | string | Yes | — |
(RecipeRun).completionReview.delivery | CanvasCompletionDelivery | Yes | Generated-output delivery evidence. A blocked state prevents a Done claim. |
(RecipeRun).completionReview.delivery.status | string | Yes | One of clear, blocked. |
(RecipeRun).completionReview.delivery.reasons | array of string | No | — |
(RecipeRun).completionReview.delivery.pendingOutputHandles | array of string | Yes | — |
(RecipeRun).completionReview.delivery.failedOutputHandles | array of string | Yes | — |
(RecipeRun).completionReview.delivery.nonDurableOutputHandles | array of string | Yes | — |
(RecipeRun).completionReview.blockingFindingCodes | array of string | Yes | — |
(RecipeRun).completionReview.advisoryFindingCodes | array of string | Yes | — |
Example
curl -X DELETE "https://app.gavana.ai/api/canvas-agent/v1/runs/run:4c7a9e12" \
-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