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

# Quickstart

> Install the SDK and run your first end-to-end request.

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](/api-reference/quickstart).

## 1. Install

```bash theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
pip install spine-sdk
```

<Note>
  Requires Python 3.9 or newer. Works on macOS, Linux, and Windows.
</Note>

## 2. Get an API key

Create a key in the [developer portal](https://platform.getspine.ai/keys).
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:

```bash theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
export SPINE_API_KEY=sk_spine_...
```

See [Authentication](/sdks/python/authentication) for key rotation, env
vars, and staging overrides.

## 3. Run your first request

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

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

### 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](/sdks/python/runs) for all the options.

## 4. Upload files with a run

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

## 5. Handle errors

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

```python theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
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](/sdks/python/errors) for the full hierarchy and
how transient failures are retried automatically.

## Next steps

<CardGroup cols={2}>
  <Card title="Runs and polling" icon="arrows-rotate" href="/sdks/python/runs">
    Stream progress, tune poll intervals, use the low-level `runs.get`.
  </Card>

  <Card title="Canvas introspection" icon="diagram-project" href="/sdks/python/canvas">
    Inspect the block graph and task tree a run produced.
  </Card>
</CardGroup>