Install and authenticate

Install

npm install @ellipsis-dev/sdk

The package is ESM only and ships its own type declarations. It has no runtime dependencies: the client uses the runtime's own fetch, so it works anywhere fetch and WebSocket are global, which covers current Node, Bun, Deno, and browsers.

Authenticate

Create an API key under Platform → API keys in the dashboard. The secret starts with ellipsis_key_ and is shown only once. Keep it in an environment variable rather than in source:

export ELLIPSIS_API_TOKEN="ellipsis_key_..."

apiKey is the client's only required option:

import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

An API key authenticates as your organization. A CLI user token, which agent login mints, authenticates as you personally and works in exactly the same option. Either is rejected with 401 if invalid or revoked.

Never ship an API key to a browser. In a browser, call your own backend and let it hold the credential.

Client options

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
  baseUrl: 'https://api.ellipsis.dev',
  timeoutMs: 60_000,
  maxRetries: 3,
});

baseUrl points the client at a non-default host. timeoutMs is per request. maxRetries bounds automatic retries, which apply to transport failures and to 429, 502, 503, and 504, with exponential backoff and jitter. A 429 response honors its Retry-After header. Other statuses are never retried: a 404 or 422 would fail identically the second time.

fetch is injectable for tests and exotic runtimes, and defaults to the global:

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
  fetch: myInstrumentedFetch,
});