> ## 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.

# API reference

> Method-by-method reference for the Spine Python SDK.

This page is a quick, skimmable reference. For conceptual guides, start
at [Quickstart](/sdks/python/quickstart). For the HTTP-level view, see
[API reference](/api-reference/overview).

## Clients

### `SpineClient(...)` — sync

```python theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
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](/api-reference/concepts/templates).

### `BlockType`

17 members covering every block type the platform produces. See
[Block types](/api-reference/concepts/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:

```python theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
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

```python theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
from spine import (
    SpineError,               # base
    SpineAPIError,
    AuthenticationError,      # 401
    BadRequestError,          # 400
    NotFoundError,            # 404
    RateLimitError,           # 429
    ServerError,              # 5xx
    SpineTimeoutError,
    SpineConnectionError,
)
```

See [Errors and retries](/sdks/python/errors).

## Retry policy

```python theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
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=...)`.