spine-sdk 0.2.0

Official Python SDK for the Spine API.

spine-sdk

Official Python SDK for the Spine API.

Create async canvas runs, poll them to completion, and introspect the resulting canvas graph and task tree — with full type hints, sync and async clients, and a built-in polling helper.

Installation

pip install spine-sdk

The package installs as spine, so you import it as:

from spine import SpineClient

Python 3.9+ is required.

Quickstart

from spine import SpineClient, Template

with SpineClient(api_key="sk_spine_...") as client:
    handle = client.runs.create(
        prompt="Research the Q4 2025 AI chip market and write a memo",
        template=Template.DEEP_RESEARCH,
    )
    result = handle.wait(timeout=600)
    print(result.final_output)
    for artifact in result.artifacts:
        print(artifact.name, artifact.download_url)

The same code in async:

import asyncio
from spine import AsyncSpineClient

async def main() -> None:
    async with AsyncSpineClient() as client:  # reads SPINE_API_KEY from env
        handle = await client.runs.create(prompt="Hello")
        result = await handle.wait()
        print(result.final_output)

asyncio.run(main())

What's in the SDK

• SpineClient and AsyncSpineClient — fully typed, context-managed HTTP clients.
• client.runs — create runs, poll them, wait for completion with exponential backoff, or stream progress snapshots.
• client.canvas — inspect the canvas block DAG and task tree for any run.
• client.webhooks — verify inbound webhook signatures and parse the event with construct_event(payload, sig_header, secret).
• Typed Pydantic models for every request and response.
• Typed exceptions (AuthenticationError, NotFoundError, BadRequestError, ServerError, SpineTimeoutError) so you can branch on the exact failure.
• Automatic retry on transient 5xx and 429 responses (honours Retry-After).

Documentation

Full reference and guides: https://docs.getspine.ai/api-reference/sdks/python

License

MIT — see LICENSE.