Skip to main content
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. 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 it’s an infinite pannable surface; through the API it’s a directed acyclic graph exposed via GET /v1/canvas/{canvas_id}/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), 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).
  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 or a single task with GET /v1/canvas/{canvas_id}/tasks/{task_id}. 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.