Skip to main content
Find it in Darwin Profile menu → Workspace settings → API Open this screen ↗
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

The API is on every plan. Plans differ only in rate limits.

​
Base URL

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 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:
1

Open Settings → API

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.
2

Create a key

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.
3

Choose its access

Pick Read only (every read scope), Full access (every scope) or Choose to tick individual scopes. Give a key only what its job needs.
4

Copy it now

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.

​
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.
It worked if you get 200 and a body like this:
Then list your five most recent conversations:
A 401 means the key is missing or wrong; a 403 with insufficient_scope means the key lacks conversations:read. See 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.
  • Writes can be retried safely with an Idempotency-Key.
  • 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:
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

Authentication and scopes

Key types, every scope and how to revoke a key.

Webhooks

Events, payloads, signatures and retries.

Browser SDK

Control the chat and listen to it from your page.

Recipes

Slack alerts, CRM sync and a nightly warehouse export.