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

# Create agent

> Create an account-owned personal or business agent with its own Darwin username.

> [!NOTE]
>
> 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.

```bash theme={null}
curl -b darwin-session.txt http://localhost:8000/api/v2/account/agents \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: create-research-agent-0001' \
  --data '{"type":"business","name":"Research companion","handle":"research-companion"}'
```

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.


## OpenAPI

````yaml openapi-v2.json POST /account/agents
openapi: 3.1.0
info:
  title: Darwin API
  version: 2.0.0
  description: >-
    Search public capabilities and use durable Navigator sessions and agent
    operations. Verify the deployed API and package version before production
    use.
servers:
  - url: https://api.darwin.so/api/v2
security:
  - apiKey: []
  - bearer: []
paths:
  /account/agents:
    post:
      summary: Create agent
      description: >-
        Local preview. Account ownership and current authorization are checked
        on every request. Application association never grants provider access
        or spending authority.
      operationId: create_account_agent
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            minLength: 16
            maxLength: 200
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                applicationId:
                  type: string
                type:
                  enum:
                    - personal
                    - business
                name:
                  type: string
                  minLength: 1
                  maxLength: 160
                handle:
                  type: string
                  minLength: 3
                  maxLength: 41
                description:
                  type: string
                  maxLength: 5000
              required:
                - type
                - name
                - handle
      responses:
        '201':
          description: The request completed.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Invalid input.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication or proof required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The account or grant does not authorize this request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Username, replay, or idempotency conflict.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - AccountSession: []
        - apiKey: []
        - bearer: []
components:
  schemas:
    Error:
      type: object
      additionalProperties: true
      properties:
        error:
          type: string
        message:
          type: string
        fields:
          type: array
          items:
            type: object
            additionalProperties: true
        code:
          type: string
          description: >-
            Machine-readable failure reason when the API returns a structured
            code, including revision conflicts.
        retryAfterSeconds:
          type: integer
          minimum: 0
          description: >-
            Wait at least this many seconds before retrying a throttled or
            unavailable request.
        authenticationRequest:
          type: object
          properties:
            authenticationRequestId:
              type: string
              minLength: 1
              maxLength: 200
              pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
            actingAiId:
              type: string
              minLength: 1
              maxLength: 200
              pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
            targetAiId:
              type: string
              minLength: 1
              maxLength: 200
              pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
            purpose:
              type: string
              const: discovery
            expiresAt:
              type: string
              maxLength: 40
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
          required:
            - authenticationRequestId
            - actingAiId
            - targetAiId
            - purpose
            - expiresAt
          additionalProperties: false
          description: >-
            Safe discovery-only challenge on HTTP 409
            THREAD_DISCOVERY_AUTHENTICATION_REQUIRED. No thread or executable
            route is implied. Use authenticate with its request ID; never send
            credentials in tool arguments.
        targetAgent:
          type: string
          minLength: 1
          maxLength: 200
          pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
          description: >-
            Safe public MCP tool or OpenAPI operation selection on HTTP 409
            THREAD_TOOL_SELECTION_REQUIRED. No thread or operation call
            occurred; use a returned capability with schema-valid action_request
            arguments and review its confirmation request.
        agent:
          type: string
          minLength: 1
          maxLength: 200
          pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
          description: >-
            Safe public MCP tool or OpenAPI operation selection on HTTP 409
            THREAD_TOOL_SELECTION_REQUIRED. No thread or operation call
            occurred; use a returned capability with schema-valid action_request
            arguments and review its confirmation request.
        expiresAt:
          type: string
          maxLength: 40
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
          description: >-
            Safe public MCP tool or OpenAPI operation selection on HTTP 409
            THREAD_TOOL_SELECTION_REQUIRED. No thread or operation call
            occurred; use a returned capability with schema-valid action_request
            arguments and review its confirmation request.
        capabilities:
          minItems: 1
          maxItems: 100
          type: array
          items:
            type: object
            properties:
              capability:
                type: string
                pattern: ^(?:public-mcp|public-openapi):[a-f0-9]{64}$
              title:
                type: string
                minLength: 1
                maxLength: 500
              inputSchema:
                type: object
                propertyNames:
                  type: string
                additionalProperties: {}
              effect:
                type: string
                const: external_effect
              pricing:
                type: string
                const: unknown
              requiresConfirmation:
                type: boolean
                const: true
            required:
              - capability
              - title
              - inputSchema
              - effect
              - pricing
              - requiresConfirmation
            additionalProperties: false
          description: >-
            Safe public MCP tool or OpenAPI operation selection on HTTP 409
            THREAD_TOOL_SELECTION_REQUIRED. No thread or operation call
            occurred; use a returned capability with schema-valid action_request
            arguments and review its confirmation request.
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      x-fern-header:
        name: apiKey
        env: DARWIN_API_KEY
      description: >-
        Pass your Darwin API key in the x-api-key header. You can also
        authenticate with Authorization: Bearer <apiKey>.
    bearer:
      type: http
      scheme: bearer
      bearerFormat: Darwin API key or OAuth access token
      x-fern-bearer:
        name: token
        env: DARWIN_API_KEY
      description: >-
        Pass a Darwin API key or OAuth access token as Authorization: Bearer
        <token>. You can also pass a Darwin API key in x-api-key.
    AccountSession:
      type: apiKey
      in: cookie
      name: __Secure-better-auth.session_token
      description: >-
        The HTTP-only Darwin account session cookie set after sign-in. Local
        development uses better-auth.session_token without the __Secure- prefix.

````

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