Skip to main content

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.

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.