Quickstart

This walks through installing spine-sdk, creating a run, waiting for it to finish, and downloading the generated artifacts. For a broader conceptual tour of the API, see the API quickstart.

1. Install

pip install spine-sdk

Requires Python 3.9 or newer. Works on macOS, Linux, and Windows.

2. Get an API key

Create a key in the developer portal. You get $5 of free credits immediately — enough for several test runs end-to-end. Keys look like sk_spine_... and are shown only once. Export it into your environment so the SDK picks it up automatically:

export SPINE_API_KEY=sk_spine_...

See Authentication for key rotation, env vars, and staging overrides.

3. Run your first request

from spine import SpineClient, Template

with SpineClient() as client:
    handle = client.runs.create(
        prompt="Summarise the Q4 2025 AI chip market in three paragraphs.",
        template=Template.MEMO,
    )
    print("Run started:", handle.run_id)

    result = handle.wait(timeout=600)
    print(result.final_output)

    for artifact in result.artifacts:
        print(artifact.name, artifact.download_url)

import asyncio
from spine import AsyncSpineClient, Template

async def main() -> None:
    async with AsyncSpineClient() as client:
        handle = await client.runs.create(
            prompt="Summarise the Q4 2025 AI chip market.",
            template=Template.MEMO,
        )
        result = await handle.wait(timeout=600)
        print(result.final_output)

asyncio.run(main())

What happens

runs.create submits the prompt and returns a RunHandle immediately.
handle.wait polls GET /v1/run/{run_id} with exponential backoff (starts at 2 s, doubles up to 30 s) until the run is terminal.
On success, result.final_output holds the synthesized markdown and result.artifacts lists downloadable files (docx, xlsx, pptx, html, png — depending on the template).

See Runs and polling for all the options.

4. Upload files with a run

handle = client.runs.create(
    prompt="Read the attached files and produce a 1-page summary.",
    template=Template.REPORT,
    files=[
        "./market_data.pdf",
        "./notes.docx",
        ("inline.md", b"# Supplementary context\n..."),
    ],
)

The SDK accepts file paths, file objects, (filename, bytes) tuples, and dict specs. Supported types are documented on File uploads.

5. Handle errors

Every failure is a subclass of SpineError. Branch on the specific types when you need to:

from spine import SpineClient, BadRequestError, AuthenticationError

try:
    with SpineClient() as client:
        client.runs.create(prompt="", template="bogus")
except BadRequestError as exc:
    print("Rejected:", exc.error_message)
except AuthenticationError:
    print("Check your SPINE_API_KEY")

See Errors and retries for the full hierarchy and how transient failures are retried automatically.

Next steps

Runs and polling

Stream progress, tune poll intervals, use the low-level runs.get.

Canvas introspection

Inspect the block graph and task tree a run produced.

Get Started

Concepts

Use with agents

Endpoints

Resources

Python SDK

TypeScript SDK

Runs

Canvas

1. Install

2. Get an API key

3. Run your first request

What happens

4. Upload files with a run

5. Handle errors

Next steps

Runs and polling

Canvas introspection

​1. Install

​2. Get an API key

​3. Run your first request

​What happens

​4. Upload files with a run

​5. Handle errors

​Next steps

Runs and polling

Canvas introspection

1. Install

2. Get an API key

3. Run your first request

What happens

4. Upload files with a run

5. Handle errors

Next steps