Skip to main content
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

MethodReturnsDescription
client.runs.create(prompt, *, template, blocks, agent_instructions, webhook_url, files)RunHandleCreate a new run and return a polling handle.
client.runs.get(run_id)GetRunResponseOne-shot status fetch.

​
RunHandle

MethodReturnsDescription
handle.refresh()GetRunResponseFetch the current state.
handle.wait(*, timeout, poll_interval, max_poll_interval)RunResultPoll until terminal; raise on timeout or failure.
handle.stream_progress(*, poll_interval)Iterator[RunProgress]Yield snapshots until terminal.
AttributeType
handle.run_idstr
handle.canvas_idstr | None
handle.create_responseCreateRunResponse

​
Canvas

MethodReturns
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=...).