Agents API

Manage registered agents within your organization.

GET /api/v1/agents

List all agents.

Query Parameters

Name	Type	Description
status	string (optional)	Filter: active, inactive, paused
page	integer (optional)	Page number (default: 1)
limit	integer (optional)	Results per page (default: 20, max: 100)

Response — 200 OK

{
  "data": [{
    "id": "agt_7f3a9c2d",
    "name": "ProcurementBot",
    "status": "active",
    "llm_provider": "openai",
    "sessions_count": 1247,
    "created_at": "2026-01-15T08:00:00Z"
  }],
  "pagination": { "page": 1, "total": 8 }
}

---

POST /api/v1/agents

Create a new agent.

Request Body

Field	Type	Description
name	string (required)	Display name for the agent
description	string (optional)	Description of what this agent does
llm_provider	string (optional)	openai | vertex | anthropic

Response — 201 Created

{
  "id": "agt_new1234",
  "name": "ProcurementBot",
  "api_key": "hk_live_a1b2c3d4e5f6...",
  "status": "inactive"
}

Save your API key immediately

The api_key is only returned in the creation response. If lost, rotate the key.

---

GET /api/v1/agents/:id

Get agent details.

---

PATCH /api/v1/agents/:id

Update agent configuration.

---

DELETE /api/v1/agents/:id

Delete agent (soft delete).

---

POST /api/v1/agents/:id/rotate-key

Rotate the agent's API key. The old key is immediately invalidated.