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

# TypeScript SDK

> Official TypeScript / JavaScript client for the Spine API.

The Spine TypeScript SDK (`spine-sdk`) is a typed, documented client for
the [Spine API](/api-reference/overview). It wraps all five public
endpoints, polls runs with configurable intervals, and narrows response
types through discriminated unions so TypeScript guides you through every
run state.

## Install

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

Works on Node.js 18 or newer, modern browsers, Deno, Bun, and Cloudflare
Workers without any extra configuration — it uses the platform's native
`fetch` and `FormData`. Full type declarations ship in the package, so
TypeScript picks them up out of the box.

## First request

```ts theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
import { Spine } from 'spine-sdk';

const client = new Spine({ apiKey: process.env.SPINE_API_KEY! });

const run = await client.runs.create({
  prompt: 'Summarise the Q4 AI chip market in 3 paragraphs.',
  template: 'memo',
});

const terminal = await client.runs.waitForCompletion(run.run_id);

if (terminal.status === 'completed') {
  console.log(terminal.result.final_output);
  for (const artifact of terminal.result.artifacts) {
    console.log(artifact.name, artifact.download_url);
  }
}
```

Prefer the `SPINE_API_KEY` environment variable so keys stay out of your
source code:

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

## What's in the box

<CardGroup cols={2}>
  <Card title="Typed run states" icon="shapes">
    `Run` is a discriminated union narrowed by `status`. The compiler
    forces you to handle each state before touching `result`, `progress`,
    or `errors`.
  </Card>

  <Card title="Auto-polling" icon="clock-rotate-left">
    `client.runs.waitForCompletion()` polls to a terminal state with
    configurable interval, timeout, and `AbortSignal` cancellation.
  </Card>

  <Card title="Typed errors" icon="triangle-exclamation">
    `SpineBadRequestError`, `SpineAuthError`, `SpineNotFoundError`,
    `SpineServerError`, `SpineTimeoutError`, and more — branch on the
    exact failure.
  </Card>

  <Card title="Runs everywhere" icon="globe">
    Node, browsers, Deno, Bun, Cloudflare Workers. One package, zero
    runtime dependencies.
  </Card>
</CardGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/sdks/typescript/quickstart">
    Full end-to-end example with uploads, polling, and artifact download.
  </Card>

  <Card title="Runs and polling" icon="arrows-rotate" href="/sdks/typescript/runs">
    All the options on `runs.create`, `waitForCompletion`, and manual polling.
  </Card>

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

  <Card title="Errors and retries" icon="triangle-exclamation" href="/sdks/typescript/errors">
    Error hierarchy and how to tune the built-in retry policy.
  </Card>
</CardGroup>