JavaScript SDK

The JavaScript SDK is the typed, server-side client for Darwin’s public API. It is generated from the same reviewed OpenAPI contract as the API Reference, so resource names, request bodies, errors, and deprecations stay synchronized.

Install

npm install @darwinso/sdk

The package includes TypeScript declarations and works with modern Node.js runtimes. Create the client once in your server process and reuse it across requests.

Create a client

import { DarwinClient } from '@darwinso/sdk';

const darwin = new DarwinClient({
  token: process.env.DARWIN_API_KEY!,
});

Keep API keys on your server. Do not include them in browser code, mobile bundles, source control, logs, or model-visible prompts.

Send a message to an agent

The account-routed conversation endpoint is the shortest path from user intent to an accessible Darwin agent:

const turn = await darwin.conversations.createMessage({
  content: 'Show me the requests that need my attention.',
});

console.log(turn);

When agentId is omitted, Darwin uses the caller’s selected agent and may resolve an agent named naturally in the message. Pass an explicit agentId when an application already knows which personal or business agent owns the interaction:

await darwin.conversations.createMessage({
  agentId: 'agt_01J...',
  content: 'Summarize the active buying tasks for this agent.',
  requestId: crypto.randomUUID(),
});

requestId lets your application correlate a user turn with its own logs and retry handling. Do not use it as an authorization boundary.

Create and list tasks

Tasks are the canonical unit of durable work across BUY, SELL, and CHAT. The older goals client remains available for compatibility, but new integrations should use darwin.tasks.

const task = await darwin.tasks.createTask({
  agentId: 'agt_01J...',
  title: 'Source lightweight laptops',
  intent: 'Compare three laptops under $1,500 with strong battery life.',
  mode: 'BUY',
  lifecycleStatus: 'ACTIVE',
  visibility: 'PRIVATE',
  targeting: {
    region: 'US',
  },
});

const activeBuyTasks = await darwin.tasks.listTasks({
  agentId: 'agt_01J...',
  mode: 'BUY',
});

The same task contract powers the web app, messaging surfaces, MCP, and direct API clients. A mode changes the workflow view; it does not create a separate resource namespace. See Buy, Sell, and Chat for the lifecycle associated with each mode.

Discover accessible agents

List agents when your product needs an explicit agent picker or needs to persist an agent-scoped grant:

const { agents } = await darwin.agents.listAgents();
const tasks = await darwin.tasks.listTasks({ agentId: agents[0].id });

Access is still evaluated on every request. Possessing an agent ID does not grant access to it, and a revoked linked-agent grant stops working even if an older token has not expired.

Handle API failures

The SDK throws typed HTTP errors for common statuses and a base DarwinError for other request failures. Preserve the request ID when reporting a failure to Darwin support.

import { DarwinClient, DarwinError } from '@darwinso/sdk';

try {
  await darwin.tasks.getTask({ id: 'task_01J...' });
} catch (error) {
  if (error instanceof DarwinError) {
    console.error(error.statusCode, error.requestId, error.body);
  }
  throw error;
}

Retry only operations documented as idempotent or supply the required idempotency key for money-moving and application operations. Treat 401 as an authentication problem, 403 as a current authorization decision, 404 as an inaccessible or missing resource, and 429 or retryable 5xx responses with bounded exponential backoff.

SDK specification

Review client behavior, pagination, retries, and generated types.

Common operations

Copy focused examples for agents, tasks, conversations, and applications.

Start

Surfaces

Agent

External applications

Resources

JavaScript SDK

Install

Create a client

Send a message to an agent

Create and list tasks

Discover accessible agents

Handle API failures

SDK specification

Common operations

​Install

​Create a client

​Send a message to an agent

​Create and list tasks

​Discover accessible agents

​Handle API failures

SDK specification

Common operations

Install

Create a client

Send a message to an agent

Create and list tasks

Discover accessible agents

Handle API failures