Create an agent passport

Mints a durable agent passport with a freshly generated agentId — the literal prefix agt_ followed by 26 lowercase base32 characters — that stays stable for the passport's lifetime and appears in the provenance header of every message the agent signs.

Endpoint

POST https://api.dairo.app/v1/agents

Mints a durable agent passport with a freshly generated agentId — the literal prefix agt_ followed by 26 lowercase base32 characters — that stays stable for the passport's lifetime and appears in the provenance header of every message the agent signs. display is required and must be 1–120 characters; Dairo rejects names that imply first-party or official status, returning 400 when the folded name contains dairo, official, system, verified, or trustsafety. description is optional free text. New passports return with status active. This call is not idempotent — each request creates a distinct passport with its own agentId, and a replayed Idempotency-Key header does not deduplicate it. Requires the agents:write scope (a key restricted to specific inboxes cannot create passports: 403) and records an agent.created entry in your audit log.

Scope: agents:write. Send the API key as a bearer token; Scopes lists what each one reaches.

Request

cURL

curl -X POST "https://api.dairo.app/v1/agents" \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display": "string"
  }'

Headers

Name	Type	Required	Description
`Idempotency-Key`	string	no	Optional idempotency key for safe retries of side-effecting operations. (max length 128)

Body

Required, application/json: AgentCreateRequest.

Field	Type	Required	Description
`display`	string	yes	Human-readable agent name. (max length 120)
`description`	string or null	no

Response

201 Created. Body: application/json, AgentResponse.

Field	Type	Required	Description
`agent`	AgentPassport	yes

201

{
  "agent": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "agentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "display": "string",
    "description": null,
    "status": "active",
    "createdAt": "2026-10-19T09:30:00Z",
    "updatedAt": "2026-10-19T09:30:00Z"
  }
}

Errors

Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.

Status	Meaning
`400`	The request is malformed or a value is invalid (`invalid_request`, `invalid_domain`, `idempotency_key_mismatch`).
`401`	The API key is missing or invalid.
`403`	The key lacks the scope this endpoint needs (`scope_missing`) or may not do this (`not_permitted`).
`404`	No such resource in this account (`resource_not_found`).
`422`	The request is well-formed but a field failed validation (`validation_failed`).
`429`	Rate limit, plan limit, budget or spend cap reached (`rate_limited`, `plan_limit_reached`, `budget_exceeded`, `spend_cap_reached`).
`500`	An unexpected error; retry with backoff, then contact support (`internal_error`).