TypeScript SDK

@meetdarwin/api is the TypeScript client for the Darwin REST API. It covers every resource in the API, with types for every object and parameter.

No runtime dependencies. It uses the global fetch, so it runs on Node 18+, Deno, Bun, Cloudflare Workers and Vercel Edge.
ESM, with type declarations for every object and parameter.
Retries, idempotency keys, cursor pagination and webhook verification built in.

Install

npm install @meetdarwin/api

pnpm add @meetdarwin/api

yarn add @meetdarwin/api

Quickstart

Create a secret key in Darwin under Integrations → API (how). Keep it on your server.

quickstart.ts

import { Darwin } from "@meetdarwin/api";

const darwin = new Darwin({ apiKey: process.env.DARWIN_API_KEY });

// Every lead captured since October 1, across every page.
for await (const conversation of darwin.conversations.list({
  has_lead: true,
  created_since: new Date("2026-10-01"),
})) {
  console.log(conversation.lead.email, conversation.outcome, conversation.page_path);
}

// Create or update a contact, keyed by email.
const contact = await darwin.contacts.create({
  email: "ada@example.com",
  first_name: "Ada",
  company: "Analytical Engines",
  external_id: "crm_00123",
  attributes: { plan: "enterprise", seats: 40 },
});

// Get a signed POST to your URL when a meeting is booked.
const endpoint = await darwin.webhookEndpoints.create({
  url: "https://example.com/webhooks/darwin",
  events: ["meeting.booked", "lead.captured"],
});
console.log(endpoint.secret); // whsec_… shown only now; store it

new Darwin() with no apiKey reads the DARWIN_API_KEY environment variable.

The client refuses to start in a browser, because a secret key there is visible to every visitor. Call Darwin from your server. To control the chat on your website, use the Browser SDK.

Options

new Darwin({
  apiKey: "dk_live_…",                     // or dk_test_…
  baseUrl: "https://api.meetdarwin.ai/v1", // default; also served at https://app.meetdarwin.ai/api/v1
  version: "2026-10-12",                   // Darwin-Version header; defaults to the version these types describe
  timeoutMs: 30_000,                       // per attempt
  maxRetries: 2,                           // retries after the first attempt
  fetch: customFetch,                      // defaults to globalThis.fetch
});

Every method also takes a last options argument for that one call: { idempotencyKey, signal, timeoutMs, maxRetries, headers }.

Resources

Parameters and fields use the API’s own names (has_lead, created_since, next_cursor), so the API reference applies word for word. Anywhere a parameter takes a time you may pass a Date or an ISO string. Responses carry timestamps as ISO strings.

Namespace	Methods
`darwin.me()`	The key: name, mode, scopes, workspace
`darwin.workspace`	`get`
`darwin.conversations`	`list`, `retrieve`
`darwin.contacts`	`list`, `create` (upsert by email; also `upsert`), `retrieve`, `update`, `erase`
`darwin.meetings`	`list`, `retrieve`
`darwin.outcomes`	`list`, `create`, `retrieve`, `update`, `delete` (`"meeting"` is Book a meeting)
`darwin.outcomeRequests`	`list`, `retrieve`
`darwin.analytics`	`get`
`darwin.events`	`list`, `retrieve`, `redeliver`
`darwin.webhookEndpoints`	`list`, `create`, `retrieve`, `update`, `delete`, `test`, `rotateSecret`, `deliveries`
`darwin.knowledge.sources`	`list`, `add`, `retrieve`, `delete`, `refresh`
`darwin.knowledge.documents`	`list`, `create`, `retrieve`, `replace`, `delete`
`darwin.agent`	`get`, `update`
`darwin.appearance`	`get`, `update`
`darwin.chatButtons`	`list`, `create`, `retrieve`, `update`, `delete`
`darwin.personalLinks`	`list`, `create`, `retrieve`, `update`, `delete`, `urls` (each person’s own address)
`darwin.linkGreetings`	`list`, `create`, `retrieve`, `update`, `delete`
`darwin.linkVisits`	`list`, `retrieve`
`darwin.experiments`	`list`, `create`, `retrieve` (with live results), `pause`, `resume`, `stop`, `promote`, `addVariant`, `updateVariant`, `deleteVariant`
`darwin.pageOpenings`	`list`, `current`, `set`, `retrieve`, `delete`
`darwin.privacy`	`erase`, `export`
`darwin.chat.sessions`	`create`, `retrieve`, `send`, `sendStream`

For an endpoint this version does not wrap yet, darwin.request(method, path, { query, body }) gets the same auth, retries and errors.

Requirements

Node 18.17 or later, or any runtime with fetch, Web Crypto and ReadableStream. MIT licensed. Release notes are in the changelog.

Pagination

One page, every item, or whole pages with a ceiling.

Errors and retries

Error classes, automatic retries and idempotency keys.

Verify webhooks

Express and Next.js receivers in a few lines.

Stream chat replies

Talk to your agent and stream its answer.

​Install

​Quickstart

​Options

​Resources

​Requirements

​Next

Pagination

Errors and retries

Verify webhooks

Stream chat replies

Install

Quickstart

Options

Resources

Requirements

Next