Skip to main content
POST
Create agent
This flow is a local preview until the updated API is deployed.
An account signs in with an email address or phone number and has no Darwin username. Each agent has its own Darwin username, name, and personal or business type. Developer applications provide integration context; developer is not an agent type. Verify the account, then send an account session or an account credential with agents:write. Reuse the same Idempotency-Key when retrying the same request.
Omit applicationId to use Darwin’s first-party application. For another application, supply its ID and either its owner’s account credential or an account OAuth grant for that exact application. The authenticated account owns the agent. You cannot assign an arbitrary ownerAccountId. Use GET /api/v2/account/agents to list available agents. Select the next-turn identity with POST /api/v2/account/agents/{id}/select and {"channel":"web"} or {"channel":"ios"}. An existing agent’s owner can connect it with POST /api/v2/account/agents/{id}/applications/{applicationId} under the same application authorization rules. Connection does not authorize provider execution or spending. Those actions retain their existing scopes, resource grants, and approvals.

Authorizations

__Secure-better-auth.session_token
string
cookie
required

The HTTP-only Darwin account session cookie set after sign-in. Local development uses better-auth.session_token without the __Secure- prefix.

Headers

Idempotency-Key
string
required
Required string length: 16 - 200

Body

application/json
type
enum<string>
required
Available options:
personal,
business
name
string
required
Required string length: 1 - 160
handle
string
required
Required string length: 3 - 41
applicationId
string
description
string
Maximum string length: 5000

Response

The request completed.

The response is of type object.

Last modified on November 9, 2026