Skip to main content
A skimmable reference. For conceptual guides, start at Quickstart. For the HTTP-level view, see the API reference.

​
Client

​
new Spine(options)

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

MethodReturnsDescription
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

{
  prompt: string;
  template?: Template;
  blocks?: BlockType[];
  agent_instructions?: string;
  webhook_url?: string;
  files?: FileInput[];
}

​
WaitForCompletionOptions

{
  pollIntervalMs?: number;   // default: 5000
  timeoutMs?: number;        // default: 900_000
  signal?: AbortSignal;
  resolveOnFailure?: boolean; // default: false
}

​
Canvas

MethodReturns
client.canvases.getDag(canvasId)Promise<Canvas>
client.canvases.getTasks(canvasId)Promise<TaskTree>
client.canvases.getTask(canvasId, taskId)Promise<Task>

​
Discriminated run union

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.

​
BlockType

17 members covering every block type the platform produces. See 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: 
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

import {
  SpineError,                // base
  SpineAPIError,
  SpineBadRequestError,      // 400
  SpineAuthError,            // 401
  SpineNotFoundError,        // 404
  SpineServerError,          // 5xx
  SpineConnectionError,
  SpineTimeoutError,
  SpineRunFailedError,
} from 'spine-sdk';
See Errors and retries.

​
Utilities

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.