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

​
What happens

  1. runs.create submits the prompt and returns a RunHandle immediately.
  2. 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.
  3. 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.