Authentication

The Spine API uses API keys sent as the X-API-KEY request header. The SDK adds the header for you on every request — you just need to give it a key.

Passing the key

// Shell:
// export SPINE_API_KEY=sk_spine_...

import { Spine } from 'spine-sdk';

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

import { Spine } from 'spine-sdk';

const client = new Spine({ apiKey: 'sk_spine_...' });

Never commit keys to source control. Use your deployment platform’s secret manager (AWS Secrets Manager, 1Password, Doppler, etc.) and inject them at runtime. Never ship keys to the browser — proxy requests through your own backend instead.

If apiKey is falsy, the Spine constructor throws immediately — before any network call.

Key rotation

Keys revoked in the dashboard stop working on the next request; you’ll see SpineAuthError thrown from the SDK. Roll new keys through your secret store before revoking the old one so running processes don’t break mid-run. The server caches keys for up to 5 minutes, so leave that grace window.

Overriding the base URL

Point the SDK at a staging or enterprise deployment via baseURL:

const client = new Spine({
  apiKey: process.env.SPINE_API_KEY!,
  baseURL: 'https://staging.getspine.ai',
});

The SDK appends /v1 paths automatically, so pass the host without the API prefix.

Tuning timeouts and retries

const client = new Spine({
  apiKey: process.env.SPINE_API_KEY!,
  timeoutMs: 60_000,   // per-request timeout (default: 60_000)
  maxRetries: 2,       // transient 5xx / network retries (default: 2)
});

See Errors and retries for the retry policy.

Injecting your own fetch

For advanced cases (custom proxies, test doubles, alternative runtimes), pass a pre-configured fetch implementation. The SDK still applies X-API-KEY and User-Agent headers — your implementation does not need to set them.

import undici from 'undici';

const client = new Spine({
  apiKey: process.env.SPINE_API_KEY!,
  fetch: undici.fetch as typeof fetch,
});

Observing requests

Use onRequest and onResponse for tracing every call:

const client = new Spine({
  apiKey: process.env.SPINE_API_KEY!,
  onRequest: ({ method, url }) => console.debug('[spine]', method, url),
  onResponse: ({ status, durationMs }) =>
    console.debug('[spine]', status, `${durationMs}ms`),
});

Get Started

Concepts

Use with agents

Endpoints

Resources

Python SDK

TypeScript SDK

Runs

Canvas

Passing the key

Key rotation

Overriding the base URL

Tuning timeouts and retries

Injecting your own fetch

Observing requests

​Passing the key

​Key rotation

​Overriding the base URL

​Tuning timeouts and retries

​Injecting your own fetch

​Observing requests

Passing the key

Key rotation

Overriding the base URL

Tuning timeouts and retries

Injecting your own fetch

Observing requests