Skip to content

Agents API

Agents are AI systems with cryptographic identities.

Create Agent

POST /v1/agents

Headers

Header Required Description
X-API-Key Yes Your API key

Request

{
  "name": "payment-processor",
  "scopes": ["payments:read", "payments:write"]
}

Response

{
  "id": "2ffacd56-86ff-483c-8c59-5686df52aff8",
  "name": "payment-processor",
  "public_key": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK...",
  "key_fingerprint": "sha256:abc123...",
  "secret": "sk_live_abc123...",
  "scopes": ["payments:read", "payments:write"],
  "status": "active",
  "created_at": "2025-01-16T14:30:00Z"
}

Save the Secret

The secret is only returned once.

Example

agent = client.agents.create(
    name="payment-processor",
    scopes=["payments:read", "payments:write"]
)

curl -X POST \
  -H "X-API-Key: aa_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "payment-processor", "scopes": ["payments:read"]}' \
  https://web-production-b910f.up.railway.app/v1/agents

List Agents

GET /v1/agents

Query Parameters

Parameter Type Description
status string Filter by status (active, suspended, revoked)
limit int Max results (default 20)
offset int Pagination offset

Response

[
  {
    "id": "2ffacd56-86ff-483c-8c59-5686df52aff8",
    "name": "payment-processor",
    "status": "active",
    "scopes": ["payments:read", "payments:write"],
    "created_at": "2025-01-16T14:30:00Z",
    "last_auth_at": "2025-01-16T15:00:00Z"
  }
]

Get Agent

GET /v1/agents/{id}

Response

{
  "id": "2ffacd56-86ff-483c-8c59-5686df52aff8",
  "name": "payment-processor",
  "public_key": "-----BEGIN PUBLIC KEY-----\n...",
  "key_fingerprint": "sha256:abc123...",
  "status": "active",
  "scopes": ["payments:read", "payments:write"],
  "created_at": "2025-01-16T14:30:00Z",
  "last_auth_at": "2025-01-16T15:00:00Z"
}

Revoke Agent

Permanently disables an agent.

DELETE /v1/agents/{id}

Response

{
  "id": "2ffacd56-86ff-483c-8c59-5686df52aff8",
  "status": "revoked",
  "revoked_at": "2025-01-16T16:00:00Z"
}

Permanent Action

Revoking an agent cannot be undone.