API reference

This page is a quick, skimmable reference. For conceptual guides, start at Quickstart. For the HTTP-level view, see API reference.

Clients

`SpineClient(...)` — sync

from spine import SpineClient

client = SpineClient(
    api_key=None,          # str | None — falls back to SPINE_API_KEY
    base_url=None,         # str | None — falls back to SPINE_BASE_URL or api.getspine.ai
    timeout=None,          # httpx.Timeout | None — default 60s total, 10s connect
    retry_policy=None,     # RetryPolicy | None — default 3 retries
    http_client=None,      # httpx.Client | None — advanced: inject your own
)

Use as a context manager (with SpineClient() as client:) so the underlying HTTP pool closes cleanly.

`AsyncSpineClient(...)` — async

Identical signature; http_client accepts an httpx.AsyncClient. Use as async with AsyncSpineClient() as client:.

Runs

Method	Returns	Description
`client.runs.create(prompt, *, template, blocks, agent_instructions, webhook_url, files)`	`RunHandle`	Create a new run and return a polling handle.
`client.runs.get(run_id)`	`GetRunResponse`	One-shot status fetch.

`RunHandle`

Method	Returns	Description
`handle.refresh()`	`GetRunResponse`	Fetch the current state.
`handle.wait(*, timeout, poll_interval, max_poll_interval)`	`RunResult`	Poll until terminal; raise on timeout or failure.
`handle.stream_progress(*, poll_interval)`	`Iterator[RunProgress]`	Yield snapshots until terminal.

Attribute	Type
`handle.run_id`	`str`
`handle.canvas_id`	`str \| None`
`handle.create_response`	`CreateRunResponse`

Canvas

Method	Returns
`client.canvas.get_dag(canvas_id)`	`CanvasDAG`
`client.canvas.get_tasks(canvas_id)`	`TaskTree`
`client.canvas.get_task(canvas_id, task_id)`	`TaskNode`

Enums

`Template`

AUTO, DEEP_RESEARCH, REPORT, SLIDES, MEMO, EXCEL, APP, LANDING_PAGE. See Templates.

`BlockType`

17 members covering every block type the platform produces. See Block types.

`RunStatus`

RUNNING, COMPLETED, PARTIAL, FAILED. status.is_terminal is True for anything except RUNNING.

Models

All models are Pydantic v2 and are re-exported from the top-level spine package:

from spine import (
    CreateRunResponse, GetRunResponse,
    RunProgress, RunResult, RunArtifact, RunMetadata, RunError,
    CanvasDAG, CanvasNode, CanvasEdge,
    TaskTree, TaskNode,
)

Each model uses extra="ignore", so new fields added to the backend don’t break old SDK releases.

Exceptions

from spine import (
    SpineError,               # base
    SpineAPIError,
    AuthenticationError,      # 401
    BadRequestError,          # 400
    NotFoundError,            # 404
    RateLimitError,           # 429
    ServerError,              # 5xx
    SpineTimeoutError,
    SpineConnectionError,
)

See Errors and retries.

Retry policy

from spine import RetryPolicy

RetryPolicy(
    max_retries=3,      # int, 0 disables retries
    base_delay=0.5,     # float seconds
    max_delay=30.0,     # float seconds
    jitter=0.1,         # float, ±fraction
)

Passed to SpineClient(retry_policy=...).

Get Started

Concepts

Use with agents

Endpoints

Resources

Python SDK

TypeScript SDK

Runs

Canvas

Clients

`SpineClient(...)` — sync

`AsyncSpineClient(...)` — async

Runs

`RunHandle`

Canvas

Enums

`Template`

`BlockType`

`RunStatus`

Models

Exceptions

Retry policy

​Clients

​SpineClient(...) — sync

​AsyncSpineClient(...) — async

​Runs

​RunHandle

​Canvas

​Enums

​Template

​BlockType

​RunStatus

​Models

​Exceptions

​Retry policy

Clients

`SpineClient(...)` — sync

`AsyncSpineClient(...)` — async

Runs

`RunHandle`

Canvas

Enums

`Template`

`BlockType`

`RunStatus`

Models

Exceptions

Retry policy