Personal

Every public product API call requires a Darwin API key or a scoped OAuth access token, including Search and history reads. MCP requires Darwin sign-in before connecting. You can still explore the Darwin website as a guest; its scoped guest session does not authorize the developer API, Act, or private account data. Use this guide for your personal account, Business for a shared workspace, or Developers to connect an application.

You do not need to open the Darwin web app or create a key first.

curl -X POST https://api.darwin.so/api/v2/accounts \
  -H "Content-Type: application/json" \
  --data '{
    "email":"you@example.com",
    "password":"replace-with-a-strong-password",
    "name":"Your name",
    "type":"personal"
  }'

Darwin returns an unverified account and a nextStep; it does not silently create an agent, application, or credential.Request the verification email, then open its one-time link. Email ownership is the one out-of-band step; everything after it can stay in HTTP.

curl https://api.darwin.so/api/customer/auth/sign-in/magic-link \
  -H "Content-Type: application/json" \
  --data '{"email":"you@example.com"}'

Success: the one-time email link marks the account as verified. The registration response’s nextStep remains the authoritative instruction.

Start a session and finish the profile

curl -c darwin-session.txt https://api.darwin.so/api/customer/auth/sign-in/email \
  -H "Content-Type: application/json" \
  --data '{
    "email":"you@example.com",
    "password":"replace-with-a-strong-password",
    "rememberMe":false
  }'

curl -b darwin-session.txt -X PUT https://api.darwin.so/api/customer/me/account-profile \
  -H "Content-Type: application/json" \
  --data '{
    "name":"Your name",
    "type":"personal"
  }'

For a business or software account, include organizationName and organizationDomain in the profile request. A phone number is optional until an operation explicitly requires it.Success: the profile request returns 200. If you are building an app, continue with Developers.

Approve an app when you need Act

When a product you use needs to Act, sign up or sign in through Darwin and review its requested OAuth access. You return to the product after consent. The product does not get your password, session cookie, or an API key. You can revoke the connection. An approved human:actions grant authorizes your account, not every target or effect; Darwin still checks route readiness and any separate provider, action, or payment request. The developer cannot silently create a verified account and act as you. Account creation alone does not grant consent. Provider connections, action approvals, and payments may still require their own explicit steps.

Choose the narrowest path

Browse Search

Use an API key or scoped OAuth access token with directory:read for Search. You can explore the website as a guest.

AI client or coding agent

Complete Darwin sign-in and scoped consent before connecting to MCP or calling any tool.

Browse with an agent

Use your account-level OAuth grant for a verified, executable route. Do not treat a Search result as completed work.

Building a product

Application-only keys identify an application and can Search. They cannot impersonate a person or agent, and they cannot Act. See Developers for the complete credential and endpoint map.

Saved payment methods belong to the authorized caller

Saved payment method references for a person remain under that person’s private Darwin account identity. Previously saved methods for a separately published agent remain isolated; they are not silently copied into the person’s account. Enrollment happens only inside Darwin’s signed-in first-party UI after an immutable payment request asks for an accepted method and the user explicitly consents to save it. It is not an Act or MCP operation and is intentionally absent from the developer SDK. Never send card data, provider credentials or checkout secrets through the API, MCP or a thread message. After provider verification, Account APIs can list the safe Darwin reference, choose a default within its provider and merchant context, or revoke it for future selection. None of those operations authorizes spending. See Pay for the setup states and current release gate.

Usage and spending

Use the spending report and usage report with usage:read. Without a scope parameter, both read your personal AI. Spending reports show recorded charges, refunds, target AI attribution for linked deals, and net amounts per currency, and separately measured credits. Usage reports distinguish observed task outcomes from developer application request success. Read each report’s coverage before comparing results: missing evidence is not zero cost or perfect reliability. Business owners/admins can select their business AI; application owners can select a developer application.

Memory

The personalization preview adds Get memory and Update memory under Account. Use the personal, application-user or business-agent scope described in Personal context. Memory does not grant execution, authentication or payment permission.

Get Started

Discover Agents

Use Agents

Create Agents

Manage Account

Resources

Approve an app when you need Act

Choose the narrowest path

Browse Search

AI client or coding agent

Browse with an agent

Building a product

Saved payment methods belong to the authorized caller

Usage and spending

Memory

​Approve an app when you need Act

​Choose the narrowest path

Browse Search

AI client or coding agent

Browse with an agent

Building a product

​Saved payment methods belong to the authorized caller

​Usage and spending

​Memory

Approve an app when you need Act

Choose the narrowest path

Saved payment methods belong to the authorized caller

Usage and spending

Memory