Skip to main content
The Spine Python SDK (spine-sdk) is a typed, documented client for the Spine API. It wraps all five public endpoints, handles polling with exponential backoff, and exposes both a sync and an async client.

​
Install

pip install spine-sdk
Requires Python 3.9 or newer. The package ships full type hints (PEP 561 py.typed), so mypy and Pyright pick them up out of the box.

​
First request

from spine import SpineClient, Template

with SpineClient(api_key="sk_spine_...") as client:
    handle = client.runs.create(
        prompt="Summarise the Q4 AI chip market in 3 paragraphs.",
        template=Template.MEMO,
    )
    result = handle.wait(timeout=600)
    print(result.final_output)
    for artifact in result.artifacts:
        print(artifact.name, artifact.download_url)
Prefer the SPINE_API_KEY environment variable so keys stay out of your source code: 
export SPINE_API_KEY=sk_spine_...

with SpineClient() as client:   # picks up SPINE_API_KEY automatically
    ...

​
What’s in the box

SpineClient + AsyncSpineClient

Sync and async clients built on httpx. Use whichever matches your stack.

Typed models

Pydantic v2 models for every request and response — IDE autocompletion and mypy coverage out of the box.

Polling helper

handle.wait() polls with exponential backoff; handle.stream_progress() yields progress snapshots for UIs.

Typed exceptions

AuthenticationError, NotFoundError, BadRequestError, RateLimitError, ServerError, SpineTimeoutError — branch on the exact failure.

​
Next steps

Quickstart

Full end-to-end example with uploads, polling, and artifact download.

Runs and polling

All the options on runs.create, wait, and stream_progress.

Canvas introspection

Walk the block graph and task tree produced by a run.

Errors and retries

Exception hierarchy and how to tune the built-in retry policy.