Actions

Discover and run deterministic, credit-free image transformations.

Base URL: https://app.gavana.ai/api/canvas-agent/v1 · Authentication: HTTP bearer, token format cba_<token-id>.<secret>

Operations

GET /actions

List deterministic Image Actions

Returns typed schemas for the eight deterministic, credit-free raster transformations available in the browser, CLI, API, and MCP adapter.

• Operation id: listImageActions
• Scopes: Requires canvas:read.
• CLI equivalent: gavana action list

Parameters

Responses

200 response body

Example

curl "https://app.gavana.ai/api/canvas-agent/v1/actions" \
  -H "Authorization: Bearer $GAVANA_AGENT_TOKEN"

GET /actions/{actionKey}

Read one Image Action schema

Returns the exact ordered image inputs, typed parameters, defaults, limits, output contract, and cost behavior for one Action.

• Operation id: getImageAction
• Scopes: Requires canvas:read.
• CLI equivalent: gavana action get

Parameters

Responses

200 response body

Example

curl "https://app.gavana.ai/api/canvas-agent/v1/actions/action:resize" \
  -H "Authorization: Bearer $GAVANA_AGENT_TOKEN"

POST /actions/{actionKey}/runs

Run a deterministic Image Action

Queues a credit-free raster transform against one or two durable node or asset handles. The result is stored as a durable asset and materialized in the selected target image node.

• Operation id: startImageAction
• Scopes: Requires canvas:read + canvas:write + asset:read.
• CLI equivalent: gavana action run

Parameters

Request body (application/json, required)

Validation rules the service enforces across these fields:

• targetNodeId must not identify any node supplied in inputs
• targetNodeId must identify an empty, unbound image node

Responses

202 response body

Callbacks

• imageJobTerminal → {$request.body#/webhook/url}: Receive a signed terminal image-job event. Gavana signs ${timestamp}.${rawBody} with HMAC-SHA256 and the caller-owned secret. Return any 2xx response to acknowledge delivery. Delivery uses 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. Successful Image and Action callbacks already contain durable asset and node handles in data.run.images, so callback-only clients do not need a follow-up GET. A caller with job:manage may read the shared Run later for inspection. Successful image and Action results retain their temporary 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.

Example

curl -X POST "https://app.gavana.ai/api/canvas-agent/v1/actions/action:resize/runs" \
  -H "Authorization: Bearer $GAVANA_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "canvasId": "canvas:8f2c1d40-9a77-4c2e-9c11-2b0a5f6d7e31",
    "baseRevision": "12",
    "idempotencyKey": "2026-08-04-first-attempt",
    "targetNodeId": "<targetNodeId>",
    "inputs": [
      "<inputs>"
    ],
    "params": {}
  }'

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.