Agents API

Manage and interact with agents in a Tenant. Most routes require Owner or Admin; POST /api/agents/:slug/chat is callable by Member. The Tenant context is resolved from the bearer token — you don't pass tenantId in the path; the platform looks it up from the User row.

List agents

GET /api/agents

200 OK
{
  "items": [
    {
      "slug": "sales",
      "name": "Sales",
      "kind": "department",
      "status": "active",
      "modelProvider": "anthropic",
      "modelName": "claude-sonnet-4-5"
    }
  ]
}

Create an agent

POST /api/agents

Request body
{
  "slug": "custom-agent",
  "name": "Custom Agent",
  "kind": "department",
  "systemPrompt": "You are ..."
}

200 OK
{ "slug": "custom-agent", "name": "Custom Agent", ... }

409 Conflict
{ "error": "slug_exists" }

Get an agent

GET /api/agents/:slug

200 OK
{
  "slug": "sales",
  "name": "Sales",
  "kind": "department",
  "parentSlug": null,
  "modelProvider": "anthropic",
  "modelName": "claude-sonnet-4-5",
  "tools": ["search_knowledge", "zapier:hubspot_create_contact", ...],
  "approvalPolicies": { ... }
}

Update an agent

PATCH /api/agents/:slug

Request body (partial)
{
  "modelName": "claude-opus-4-7",
  "systemPrompt": "Updated prompt ..."
}

200 OK
{ "slug": "sales", ... }

Pause / resume

POST /api/agents/:slug/pause — agent stops accepting inbound chat; existing in-flight calls finish.
POST /api/agents/:slug/resume — re-enable.

200 OK
{ "slug": "sales", "status": "paused" }

Archive / restore

POST /api/agents/:slug/archive — soft-delete; row is retained but hidden from list endpoints.
POST /api/agents/:slug/restore — un-archive.

Chat

POST /api/agents/:slug/chat

Request body
{
  "text": "Look up the latest invoice for Customer X",
  "threadId": "thread_01"   // optional; new thread if omitted
}

200 OK
{
  "messageId": "msg_01",
  "threadId": "thread_01",
  "reply": "The latest invoice for Customer X is ...",
  "toolCalls": [...]
}

429 Too Many Requests
{ "error": "rate_limited",
  "detail": "Per-tenant chat quota exceeded" }

Rate-limited per (tenantId, userId) (see Concepts — Security). Spend-cap auto-pause fires at 100% of SPEND_CAP_USD.

Chat history

GET /api/agents/:slug/chat/messages?threadId=...

200 OK
{
  "items": [
    { "id": "msg_00", "role": "user",      "text": "..." },
    { "id": "msg_01", "role": "assistant", "text": "..." }
  ]
}

Usage

GET /api/agents/:slug/usage — per-agent token + cost rollup. Used by the /costs console page.

Knowledge base under an agent

POST /api/agents/:slug/kb — create a KB file scoped to this agent.
POST /api/agents/:slug/kb/upload — multipart upload.
PATCH /api/agents/:slug/kb/:fileId — rename or update metadata.
DELETE /api/agents/:slug/kb/:fileId — remove.

MCP allowlist

GET /api/agents/:slug/mcp-servers — servers this agent can talk to.
PUT /api/agents/:slug/mcp-servers/:serverId — toggle on / off for this agent.
GET /api/agents/:slug/mcp-tools — resolved tool catalogue (custom + every MCP server's tool list, namespaced).

Broadcast

POST /api/agents/broadcast — send a message into every agent in the Tenant simultaneously (useful for end-of-day-status round-ups).

Source: src/platform/api.ts + src/platform/chat-api.ts.