Skip to main content
The Darwin SDK is the typed JavaScript and TypeScript wrapper 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

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

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 AI

The account-routed conversation endpoint is the shortest path from user intent to an accessible Darwin AI:
When aiId is omitted, Darwin uses the caller’s selected AI and may resolve an AI named naturally in the message. Pass an explicit aiId when an application already knows which personal or business AI owns the interaction:
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 goals

Goals are the canonical unit of durable work across BUY, SELL, and CHAT. The older tasks client remains available for compatibility, but new integrations should use darwin.goals.
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, Supply, and Chat for the lifecycle associated with each mode.

Discover accessible AIs

List AIs when your product needs an explicit AI picker or needs to persist an AI-scoped grant:
Access is still evaluated on every request. Possessing an AI ID does not grant access to it, and a revoked linked AI 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.
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 AIs, goals, conversations, and applications.