> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meetdarwin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> Install @meetdarwin/api, the typed TypeScript client for the Darwin REST API: conversations, contacts, meetings, outcome forms, personal links, webhooks, knowledge, the agent and the chat API, with retries, idempotency and pagination built in.

`@meetdarwin/api` is the TypeScript client for the [Darwin REST API](https://docs.meetdarwin.ai/api-reference/introduction.md). 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

```bash npm theme={null}
npm install @meetdarwin/api
```

```bash pnpm theme={null}
pnpm add @meetdarwin/api
```

```bash yarn theme={null}
yarn add @meetdarwin/api
```

## Quickstart

Create a secret key in Darwin under **Integrations → API** ([how](https://docs.meetdarwin.ai/api-reference/authentication.md)). Keep it on your server.

```ts quickstart.ts theme={null}
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.

> [!WARNING]
>
> 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](https://docs.meetdarwin.ai/api-reference/browser-sdk.md).

## Options

```ts theme={null}
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](https://docs.meetdarwin.ai/api-reference/introduction.md) 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](https://docs.meetdarwin.ai/changelog.md).

## Next

> **[Pagination](https://docs.meetdarwin.ai/sdks/typescript/pagination.md)**
>
> One page, every item, or whole pages with a ceiling.

> **[Errors and retries](https://docs.meetdarwin.ai/sdks/typescript/errors.md)**
>
> Error classes, automatic retries and idempotency keys.

> **[Verify webhooks](https://docs.meetdarwin.ai/sdks/typescript/webhooks.md)**
>
> Express and Next.js receivers in a few lines.

> **[Stream chat replies](https://docs.meetdarwin.ai/sdks/typescript/chat.md)**
>
> Talk to your agent and stream its answer.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.