# Gavana Canvas API V1.0.0

> Generated from the stable OpenAPI contract. Use the JSON document for code generation and this page for a compact human- and agent-readable index.

Base URL: `https://app.gavana.ai/api/canvas-agent/v1`

Authentication: `Authorization: Bearer cba_...`

Every response includes `X-Request-ID`. The active Canvas, Recipe, asset, Action, model, and provider list endpoints preserve their named array and include `page.limit`, `page.hasMore`, and opaque `page.nextCursor` fields.

## Operations

| Method | Path | Summary | Required scopes | CLI |
| --- | --- | --- | --- | --- |
| GET | `/auth/status` | Verify the current Agent Access token | none | `gavana auth status` |
| GET | `/actions` | List deterministic Image Actions | `canvas:read` | `gavana action list` |
| GET | `/actions/{actionKey}` | Read one Image Action schema | `canvas:read` | `gavana action get` |
| POST | `/actions/{actionKey}/runs` | Run a deterministic Image Action | `canvas:read`, `canvas:write`, `asset:read` | `gavana action run` |
| GET | `/assets` | List accessible assets | `asset:read` | `gavana asset list` |
| POST | `/assets` | Upload a durable raster reference | `asset:read`; plus one of `image:generate` or `video:generate`; additionally when canvasId query parameter is present: `canvas:read`, `canvas:write` | `gavana asset upload` |
| GET | `/assets/{assetId}` | Get an accessible asset | `asset:read` | `gavana asset get` |
| GET | `/assets/preview` | Read a short-lived scoped image preview | none | — |
| GET | `/campaigns` | List legacy campaign runs (deprecated) | `canvas:read`, `canvas:write`, `asset:read`, `image:generate`, `job:manage` | — |
| GET | `/campaigns/{runId}` | Get a legacy campaign run (deprecated) | `canvas:read`, `canvas:write`, `asset:read`, `image:generate`, `job:manage` | — |
| DELETE | `/campaigns/{runId}` | Cancel a legacy campaign run (deprecated) | `canvas:read`, `canvas:write`, `asset:read`, `image:generate`, `job:manage` | — |
| POST | `/campaigns/{runId}/review` | Review a legacy campaign run (deprecated) | `canvas:read`, `canvas:write`, `asset:read`, `image:generate`, `job:manage` | — |
| POST | `/campaigns/plan` | Plan a legacy campaign (deprecated) | `canvas:read`, `canvas:write`, `asset:read` | — |
| POST | `/campaigns/start` | Start a legacy campaign (deprecated) | `canvas:read`, `canvas:write`, `asset:read`, `image:generate`, `job:manage` | — |
| GET | `/canvases` | List accessible canvases | `canvas:read` | `gavana canvas list` |
| POST | `/canvases` | Create a canvas or resolve Agent Canvas | `canvas:read`, `canvas:write` | `gavana canvas create` |
| GET | `/canvases/{canvasId}` | Get a complete canvas and its current revision | `canvas:read` | `gavana canvas get` |
| GET | `/canvases/{canvasId}/nodes/{nodeId}` | Get one node with incoming and outgoing connections | `canvas:read` | `gavana node get` |
| POST | `/canvases/{canvasId}/operations` | Validate or apply one revision-safe operation batch | `canvas:read`; additionally when validateOnly is not true: `canvas:write` | `gavana canvas apply` |
| POST | `/canvases/{canvasId}/workflows` | Create a private reusable workflow without running it | `canvas:read`, `canvas:write` | — |
| GET | `/canvases/{canvasId}/render` | Render a canvas as SVG | `canvas:read` | `gavana canvas render` |
| POST | `/images/edit` | Queue an image edit | `canvas:read`, `canvas:write`, `asset:read`, `image:generate` | `gavana image edit` |
| POST | `/images/generate` | Queue image generation | `canvas:read`, `canvas:write`, `asset:read`, `image:generate` | `gavana image generate` |
| POST | `/images/import` | Import a public HTTPS image as a durable canvas node | `canvas:read`, `canvas:write`, `asset:read`, `image:generate` | — |
| POST | `/images/variations` | Queue image variations | `canvas:read`, `canvas:write`, `asset:read`, `image:generate` | `gavana image variations` |
| POST | `/videos/generate` | Queue video generation | `canvas:read`, `asset:read`, `video:generate` | `gavana video generate` |
| GET | `/jobs/{jobId}` | Read or finalize an image, Action, or video job | `job:manage` | `gavana job get` |
| DELETE | `/jobs/{jobId}` | Cancel an image, Action, or video job | `job:manage` | `gavana job cancel` |
| GET | `/jobs/{jobId}/output` | Download completed video output | `job:manage` | `gavana video download` |
| GET | `/models` | List runnable image and video models | one of `image:generate` or `video:generate` | `gavana model list` |
| GET | `/models/{modelKey}` | Read an image or video model schema | one of `image:generate` or `video:generate` | `gavana model get` |
| GET | `/providers` | List saved image and video provider connections | one of `image:generate` or `video:generate` | `gavana provider list` |
| GET | `/recipes` | Search approved Recipes | `canvas:read` | `gavana recipe search` |
| GET | `/recipes/{recipeId}` | Get an approved Recipe | `canvas:read` | `gavana recipe get` |
| POST | `/recipes/{recipeId}/fork` | Fork a Recipe into a canvas without running it | `canvas:read`, `canvas:write` | `gavana recipe fork` |
| POST | `/recipes/{recipeId}/runs` | Run a Recipe explicitly | `canvas:read`, `canvas:write`, `asset:read`, `image:generate` | `gavana recipe run` |
| GET | `/runs/{runId}` | Read or advance a shared Run | `job:manage` | `gavana run get` |
| DELETE | `/runs/{runId}` | Cancel a shared Run | `job:manage` | `gavana run cancel` |

## Machine-readable contract

- [OpenAPI 3.1 JSON](https://app.gavana.ai/openapi/canvas-agent-v1.json)
- [LLM index](https://app.gavana.ai/llms.txt)
- [Complete API and CLI context](https://app.gavana.ai/llms-full.txt)

Do not put Agent Access tokens in URLs, screenshots, logs, or support messages. Share the response request ID when asking for support.