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

# API reference

> Method-by-method reference for the Spine TypeScript SDK.

A skimmable reference. For conceptual guides, start at
[Quickstart](/sdks/typescript/quickstart). For the HTTP-level view, see
the [API reference](/api-reference/overview).

## Client

### `new Spine(options)`

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

const client = new Spine({
  apiKey,                // string — required, falls back to none (no env-var auto-load)
  baseURL,               // string — defaults to "https://api.getspine.ai"
  timeoutMs,             // number — per-request timeout, default 60_000
  maxRetries,            // number — transient-failure retries, default 2
  fetch,                 // typeof fetch — inject a custom implementation
  onRequest,             // hook — fires before each request
  onResponse,            // hook — fires after each response
});
```

## Runs

| Method                                           | Returns                | Description                                        |
| ------------------------------------------------ | ---------------------- | -------------------------------------------------- |
| `client.runs.create(params)`                     | `Promise<CreatedRun>`  | Submit a new run.                                  |
| `client.runs.retrieve(runId)`                    | `Promise<Run>`         | One-shot status fetch.                             |
| `client.runs.waitForCompletion(runId, options?)` | `Promise<TerminalRun>` | Poll until terminal; throws on timeout or failure. |

### `CreateRunParams`

```ts theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
{
  prompt: string;
  template?: Template;
  blocks?: BlockType[];
  agent_instructions?: string;
  webhook_url?: string;
  files?: FileInput[];
}
```

### `WaitForCompletionOptions`

```ts theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
{
  pollIntervalMs?: number;   // default: 5000
  timeoutMs?: number;        // default: 900_000
  signal?: AbortSignal;
  resolveOnFailure?: boolean; // default: false
}
```

## Canvas

| Method                                      | Returns             |
| ------------------------------------------- | ------------------- |
| `client.canvases.getDag(canvasId)`          | `Promise<Canvas>`   |
| `client.canvases.getTasks(canvasId)`        | `Promise<TaskTree>` |
| `client.canvases.getTask(canvasId, taskId)` | `Promise<Task>`     |

## Discriminated run union

```ts theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
type Run = RunningRun | CompletedRun | PartialRun | FailedRun;
type TerminalRun = CompletedRun | PartialRun | FailedRun;
```

Narrow on `status` to access state-specific fields — `result`,
`progress`, `duration_ms`, `errors`.

## String enums

### `Template`

`'auto'`, `'deep_research'`, `'report'`, `'slides'`, `'memo'`,
`'excel'`, `'app'`, `'landing_page'`. See
[Templates](/api-reference/concepts/templates).

### `BlockType`

17 members covering every block type the platform produces. See
[Block types](/api-reference/concepts/block-types).

### `RunStatus`

`'running'`, `'completed'`, `'partial'`, `'failed'`.

### `TaskType`

`'parent-task'`, `'persona-task'`, `'tool-call-task'`.

## Types

All exported from the top-level `spine-sdk` package:

```ts theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
import type {
  // Run types
  Run, TerminalRun, RunningRun, CompletedRun, PartialRun, FailedRun, RunEcho,
  // Core types
  RunProgress, RunResult, RunMetadata, RunErrorEntry, Artifact,
  Block, Edge, Canvas, Task, TaskTree,
  // Options
  SpineOptions, CreateRunParams, CreatedRun, WaitForCompletionOptions, FileInput,
  // Hooks
  FetchLike, OnRequestHook, OnResponseHook,
} from 'spine-sdk';
```

## Errors

```ts theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
import {
  SpineError,                // base
  SpineAPIError,
  SpineBadRequestError,      // 400
  SpineAuthError,            // 401
  SpineNotFoundError,        // 404
  SpineServerError,          // 5xx
  SpineConnectionError,
  SpineTimeoutError,
  SpineRunFailedError,
} from 'spine-sdk';
```

See [Errors and retries](/sdks/typescript/errors).

## Utilities

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

// Fetch an artifact as a Blob.
const blob = await downloadArtifact(artifact, { signal });

// Client-side UUID validation (same rule the SDK applies before any HTTP call).
isUuid('550e8400-e29b-41d4-a716-446655440000'); // true

// Published SDK version string.
console.log(VERSION);
```

## Runtime support

* Node.js ≥ 18 (native `fetch`, `FormData`, `Blob`).
* Modern browsers.
* Deno (via npm specifier).
* Bun.
* Cloudflare Workers and other V8-isolate edge runtimes.

The package ships as dual ESM / CJS with full `.d.ts` bundles. Zero
runtime dependencies.