> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getspine.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Canvases and runs

> How runs, canvases, blocks, and tasks fit together.

The Spine API has four core concepts. Understanding how they relate makes the rest of the reference make sense.

## Run

A **run** is a single invocation of the API. You create one with [`POST /v1/run`](/api-reference/endpoints/create-run). A run moves through `running` → `completed` (or `partial` / `failed`) and eventually produces a synthesized `final_output` and zero or more downloadable `artifacts`.

A run has a 1:1 relationship with a canvas: each run generates exactly one new canvas.

## Canvas

A **canvas** is the workspace that blocks and connections live on. In the visual [Spine app](/app/canvas) it's an infinite pannable surface; through the API it's a directed acyclic graph exposed via [`GET /v1/canvas/{canvas_id}/dag`](/api-reference/endpoints/get-canvas-dag).

Agents build the canvas for you: they decompose your prompt into subtasks, pick the right block types, and wire them together so outputs from one block feed into the next.

## Block

A **block** is a single computational node — one AI prompt, one document generation, one web fetch, one image. Blocks are the units of work on the canvas. Each block has a `type` (one of 17 — see [Block types](/api-reference/concepts/block-types)), a `status`, a `content` field with its output, and optional `url` / `sources` references.

You can constrain which block types agents are allowed to create in three ways, in order of precedence:

1. Pass an explicit `blocks` array on the run request.
2. Pass a `template` (a curated block preset — see [Templates](/api-reference/concepts/templates)).
3. Let it default to `auto`, which allows all 17 types.

## Task

A **task** is execution metadata, not canvas content. Tasks form a three-level hierarchy that mirrors how agents decompose work internally:

* **Parent-task** — a high-level goal (e.g., "Produce the Q1 performance report").
* **Persona-task** — a sub-task assigned to a specialized persona agent (e.g., "Finance analyst: draft the executive summary").
* **Tool-call-task** — an atomic tool invocation (e.g., "Call the Excel generator").

Fetch the full tree with [`GET /v1/canvas/{canvas_id}/tasks`](/api-reference/endpoints/get-canvas-tasks) or a single task with [`GET /v1/canvas/{canvas_id}/tasks/{task_id}`](/api-reference/endpoints/get-task). Tasks are most useful for debugging, building observability UIs, or displaying agent progress to end users.

## How they connect

```
Run (POST /v1/run)
 └── Canvas (1:1 with run)
      ├── Blocks (DAG nodes, exposed via /dag)
      └── Tasks  (execution tree, exposed via /tasks)
```

A typical integration looks like: create a run, poll until terminal, display `final_output` and link the `artifacts`. If you want richer UX — e.g. a live agent-progress view — also pull the task tree while the run is in flight.