---
title: "Create a canvas run"
method: POST
path: "/v1/run"
tags: ["Runs"]
---

# Create a canvas run

`POST /v1/run`

## Request

- Base URL: `https://api.getspine.ai`
- URL: `https://api.getspine.ai/v1/run`
- Auth: API key in header `X-API-KEY`

Submit a prompt to trigger an async canvas run. Agents orchestrate a
DAG of blocks to satisfy the prompt; poll `GET /v1/run/{run_id}`
until status becomes `completed`, `partial`, or `failed`.

## Request body `multipart/form-data`

- CreateRunRequest
  - `prompt` string, required: What you want the agents to do.
  - `template` 'auto' | 'deep_research' | 'report' | 'slides' | 'memo' | 'excel' | 'app' | 'landing_page': Preset that controls which block types agents are allowed to create.
  - `blocks` string: JSON-encoded array of block types to override the template, e.g. `["document-block","table-block","image-block"]`. Precedence: `blocks` > `template` > `auto`.
  - `agent_instructions` string: Behavioral guidance applied across all agent layers (tone, rigor, audience, citation requirements, etc.).
  - `webhook_url` string, uri: Reserved for future webhook delivery — not yet honored.
  - `files` string[]: Optional file attachments. Images (PNG, JPEG, GIF, WEBP, SVG) become image-blocks; documents (PDF, DOCX, XLSX, CSV, TXT, MD, YAML, JSON, ZIP) become indexed file-blocks.

## Response `200`

Run accepted. Poll `poll_url` for status and results.

- CreateRunResponse
  - `success` true, required
  - `data` object, required
    - `run_id` string, uuid, required
    - `status` 'running' | 'completed' | 'partial' | 'failed', required
    - `poll_url` string, required: Relative URL to poll for status.
    - `estimated_duration_ms` integer: Heuristic duration estimate in milliseconds. Runs typically take 10–20 minutes; complex research can take up to 2 hours.

## Other responses

- `400`: Malformed request (bad template, blocks, or UUID).
- `401`: Missing, invalid, or revoked API key.
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/getspine/apis/spine-api.md) - [All operations](https://skmtc.dev/getspine/apis/spine-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getspine/apis/spine-api/revisions/5fc71da27327?raw)