Dairo Docs
GuidesAPI referenceDashboard
API referenceAgents

Get an agent passport

Fetches one agent passport by either its id (uuid) or its portable agentId (agt_...); Dairo selects the lookup column from the agt_ prefix.

Endpoint
GET https://api.dairo.app/v1/agents/{id}

Fetches one agent passport by either its id (uuid) or its portable agentId (agt_...); Dairo selects the lookup column from the agt_ prefix. Returns the passport under { "agent": {...} } with id, agentId, display, description, status (active, suspended, or revoked), createdAt, and updatedAt. Requires the agents:read scope. The lookup is project-scoped, so a passport that belongs to another organization returns 404 rather than leaking the record.

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

Request

cURL
curl "https://api.dairo.app/v1/agents/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $DAIRO_API_KEY"

Path parameters

NameTypeRequiredDescription
idstringyesAgent UUID or portable agentId (agt_...).

Response

200 Success. Body: application/json, AgentResponse.

FieldTypeRequiredDescription
agentAgentPassportyes
200
{
  "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.

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

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.

Delete an agent passport

Deprovisions an agent passport, addressed by id (uuid) or portable agentId (agt_...).

On this page

RequestPath parametersResponseErrors