> ## 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.
# Darwin API
> Use the Darwin API to read conversations, contacts, meetings and analytics, manage knowledge and the agent, and receive signed webhooks. Base URL, keys, scopes and versioning.
The Darwin API lets your own code and tools work with your workspace. Everything you can see in Darwin is available as JSON, and the changes you make in Agent Studio and Experiments can be made from code.
## What you can build
| You want to | Use |
| - | - |
| Send leads, meetings and requests for a person to your CRM, Slack or a warehouse as they happen | [Webhooks](/api-reference/webhooks) |
| Sync conversations, contacts and meetings on a schedule | REST: `GET /conversations`, `/contacts`, `/meetings` with `updated_since` |
| Report on the funnel, pages, sources and conversation quality | REST: `GET /analytics` |
| Keep the agent's knowledge current from your CMS or help center | REST: `/knowledge/sources` and `/knowledge/documents` |
| Change the agent, its look, its chat buttons and its opening tests | REST: `/agent`, `/appearance`, `/chat_buttons`, `/experiments` |
| Open the chat, recognise signed-in visitors and track bookings on your website | [Browser SDK](/api-reference/browser-sdk) |
| Let Claude, ChatGPT or Cursor read results and manage the agent | [MCP server](/api-reference/mcp) |
| Answer a person's request to see or delete their data | [Privacy](/api-reference/privacy) |
The API is on every plan. Plans differ only in [rate limits](/api-reference/rate-limits).
## Base URL
```text theme={null}
https://api.meetdarwin.ai/v1
```
**Settings → API** shows the same API at `https://app.meetdarwin.ai/api/v1`. Both addresses reach the same endpoints; examples in these docs use the first. The machine-readable [OpenAPI 3.1 spec](https://app.meetdarwin.ai/api/v1/openapi.json) describes every endpoint and is what the endpoint pages in this section are built from.
## Authenticate
Every request carries a secret key in the `Authorization` header:
```http theme={null}
Authorization: Bearer dk_live_...
```
Open the menu under your name, choose **Workspace settings**, then the **API** tab. You need to be an owner or admin to create keys; members can see this screen but not change it.
Select **Create key**. Name it after where it will be used, for example **Zapier** or **Warehouse sync**, so you know what stops working if you revoke it.
Pick **Read only** (every read scope), **Full access** (every scope) or **Choose** to tick individual [scopes](/api-reference/authentication#scopes). Give a key only what its job needs.
Darwin shows the key once. Store it where your code reads secrets, such as an environment variable or a secrets manager. Darwin keeps only a fingerprint, so a lost key cannot be shown again; create a new one instead.
More on prefixes, scopes, revoking and storage: [Authentication](/api-reference/authentication).
## Make your first request
`GET /me` needs no scope and tells you which workspace and scopes a key has. It is the quickest way to check a key works.
```bash curl theme={null}
curl https://api.meetdarwin.ai/v1/me \
-H "Authorization: Bearer $DARWIN_API_KEY"
```
```javascript Node theme={null}
const res = await fetch("https://api.meetdarwin.ai/v1/me", {
headers: { Authorization: `Bearer ${process.env.DARWIN_API_KEY}` },
});
console.log(res.status, await res.json());
```
```python Python theme={null}
import os, requests
res = requests.get(
"https://api.meetdarwin.ai/v1/me",
headers={"Authorization": f"Bearer {os.environ['DARWIN_API_KEY']}"},
)
print(res.status_code, res.json())
```
**It worked if** you get `200` and a body like this:
```json theme={null}
{
"object": "api_key_identity",
"key": "key_4k2m9q1x7z3c5v8b",
"name": "Warehouse sync",
"kind": "secret_key",
"mode": "live",
"scopes": ["analytics:read", "contacts:read", "conversations:read", "meetings:read"],
"workspace": "6f1c2b9e-4d1a-4f6b-9a3e-2c7d8e9f0a1b"
}
```
Then list your five most recent conversations:
```bash theme={null}
curl "https://api.meetdarwin.ai/v1/conversations?limit=5" \
-H "Authorization: Bearer $DARWIN_API_KEY"
```
A `401` means the key is missing or wrong; a `403` with `insufficient_scope` means the key lacks `conversations:read`. See [Errors](/api-reference/errors).
## Requests and responses
* Send and receive JSON. Request bodies use `Content-Type: application/json`; bodies are limited to 256 KB unless an endpoint says otherwise.
* Times are ISO 8601 in UTC, for example `2026-10-12T09:30:00.000Z`.
* Every object has a prefixed id that tells you what it is: `conv_` conversation, `ct_` contact, `mtg_` meeting, `evt_` event, `we_` webhook endpoint, `src_` knowledge page, `doc_` document, `exp_` opening test, `btn_` chat button, `chs_` chat session.
* Lists share one shape and use [cursor pagination](/api-reference/pagination).
* Writes can be retried safely with an [Idempotency-Key](/api-reference/idempotency).
* Conversation and meeting lists leave out your own preview chats unless you pass `include_test=true`. Nothing the API does counts as a website visitor in your analytics.
## Request ids
Every response, success or error, carries an `X-Request-Id` header such as `req_8m2k4p0q1x7z9c3v5b6n`. Errors repeat it as `request_id` in the body. Log it; it is the fastest way for Darwin support to find a call. **Settings → API → Recent requests** shows the last 50 calls from any key in the past 30 days, with status, error code, duration and the key that made them.
## Versioning
The API is versioned by date. The current version is `2026-10-12`, and every response says which version answered in a `Darwin-Version` header. Webhook payloads carry the same value as `api_version`.
You can pin a version by sending the header yourself:
```http theme={null}
Darwin-Version: 2026-10-12
```
Pinning is optional today because there is only one version. When a later version changes a response shape, a pinned integration keeps getting the shape it was built for. Darwin adds new fields and new endpoints without a new version, so write clients that ignore fields they don't know. A version Darwin does not recognise returns `400` with the code `unsupported_version`.
## Next
Key types, every scope and how to revoke a key.
Events, payloads, signatures and retries.
Control the chat and listen to it from your page.
Slack alerts, CRM sync and a nightly warehouse export.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.