Agents API

The Agents API allows you to create, manage, and configure AI agents that interact with the Agent OTP service.

Endpoints

  • GET /v1/agents - List all agents
  • POST /v1/agents - Create a new agent
  • GET /v1/agents/:id - Get an agent
  • PUT /v1/agents/:id - Update an agent
  • DELETE /v1/agents/:id - Delete an agent
  • POST /v1/agents/:id/rotate-key - Rotate API key

List Agents

Get all agents for your account.

Request

GET /v1/agents?active=true
Authorization: Bearer your_user_token

Query Parameters

ParameterTypeDescription
activebooleanFilter by active status
limitnumberResults per page (default: 20)
cursorstringPagination cursor

Response

{
  "data": [
    {
      "id": "agent_xxxxxxxxxxxx",
      "name": "Invoice Bot",
      "description": "Handles invoice generation and sending",
      "api_key_prefix": "ak_live_",
      "metadata": {
        "environment": "production",
        "team": "billing"
      },
      "is_active": true,
      "last_activity_at": "2026-01-28T11:45:00Z",
      "created_at": "2026-01-15T10:00:00Z",
      "updated_at": "2026-01-28T11:45:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Create Agent

Create a new agent and receive its API key.

Request

POST /v1/agents
Content-Type: application/json
Authorization: Bearer your_user_token

Body Parameters

FieldTypeRequiredDescription
namestringYesAgent name (max 255 chars)
descriptionstringNoAgent description
metadataobjectNoCustom metadata

Example Request

{
  "name": "Customer Support Bot",
  "description": "Handles customer inquiries and ticket management",
  "metadata": {
    "environment": "production",
    "team": "support",
    "version": "1.2.0"
  }
}

Response

{
  "id": "agent_xxxxxxxxxxxx",
  "name": "Customer Support Bot",
  "description": "Handles customer inquiries and ticket management",
  "api_key": "ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "api_key_prefix": "ak_live_",
  "metadata": {
    "environment": "production",
    "team": "support",
    "version": "1.2.0"
  },
  "is_active": true,
  "created_at": "2026-01-28T12:00:00Z",
  "updated_at": "2026-01-28T12:00:00Z"
}

Important: The full api_key is only returned once during creation. Store it securely immediately.

Get Agent

GET /v1/agents/:id
Authorization: Bearer your_user_token

Update Agent

PUT /v1/agents/:id
Content-Type: application/json
Authorization: Bearer your_user_token
{
  "name": "Updated Agent Name",
  "description": "Updated description",
  "metadata": {
    "version": "2.0.0"
  },
  "is_active": true
}

Delete Agent

Deleting an agent revokes its API key and removes all associated data.

DELETE /v1/agents/:id
Authorization: Bearer your_user_token

Warning: This action is irreversible. All permission history and tokens for this agent will be permanently deleted.

Rotate API Key

Generate a new API key for an agent. The old key remains valid for a grace period (default: 24 hours).

Request

POST /v1/agents/:id/rotate-key
Content-Type: application/json
Authorization: Bearer your_user_token
{
  "grace_period": 86400,
  "revoke_immediately": false
}

Parameters

FieldTypeDescription
grace_periodnumberSeconds before old key expires (default: 86400)
revoke_immediatelybooleanImmediately revoke old key (default: false)

Response

{
  "id": "agent_xxxxxxxxxxxx",
  "api_key": "ak_live_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
  "api_key_prefix": "ak_live_",
  "old_key_expires_at": "2026-01-29T12:00:00Z"
}

Agent Statistics

Get usage statistics for an agent.

GET /v1/agents/:id/stats?period=30d
Authorization: Bearer your_user_token

Response

{
  "period": "30d",
  "total_requests": 1250,
  "approved_requests": 1100,
  "denied_requests": 50,
  "pending_requests": 25,
  "expired_requests": 75,
  "tokens_issued": 1100,
  "tokens_used": 1050,
  "tokens_revoked": 10,
  "avg_approval_time_ms": 1250
}

See Also