Agents API

Manage your agent fleet programmatically — provision new agents, update configuration, check status, and remove agents that are no longer needed.

Endpoints

GET /api/agents 🔒 Auth required

List all agents in your workspace.

Query parameters

Parameter	Type	Description
`status`	string	Filter by status: `online`, `offline`, `degraded`
`limit`	integer	Results per page (default: 20, max: 100)
`offset`	integer	Pagination offset (default: 0)

Response

{
  "data": [
    {
      "id": "agent_01jq8abc",
      "name": "Nova",
      "role": "Research Analyst",
      "status": "online",
      "model": "claude-haiku-3.5",
      "createdAt": "2026-01-15T09:00:00Z",
      "lastActiveAt": "2026-03-17T07:58:12Z",
      "tokensTodayInput": 18420,
      "tokensTodayOutput": 4230
    }
  ],
  "pagination": {
    "total": 8,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}

POST /api/agents 🔒 Auth required

Create a new agent.

Request body

{
  "name": "Nova",
  "role": "Research Analyst",
  "description": "Monitors the competitive landscape and surfaces intelligence",
  "config": {
    "model": {
      "default": "claude-haiku-3.5",
      "fallbacks": ["claude-sonnet-4-20250514"]
    },
    "tools": {
      "allowed": ["web_search", "memory_search", "memory_store", "send_message"]
    },
    "limits": {
      "dailyTokenBudget": 300000,
      "monthlyTokenBudget": 6000000,
      "alertThreshold": 0.8
    }
  }
}

Field	Required	Description
`name`	Yes	Display name (must be unique within your workspace)
`role`	No	Short role label
`description`	No	One-sentence description
`config`	No	Agent configuration object — see Agent Configuration

Response

Returns the created agent object with 201 Created.

{
  "id": "agent_01jq8abc",
  "name": "Nova",
  "role": "Research Analyst",
  "status": "provisioning",
  "createdAt": "2026-03-17T10:00:00Z"
}

GET /api/agents/:id 🔒 Auth required

Retrieve a single agent by ID.

Response

{
  "id": "agent_01jq8abc",
  "name": "Nova",
  "role": "Research Analyst",
  "description": "Monitors the competitive landscape and surfaces intelligence",
  "status": "online",
  "model": "claude-haiku-3.5",
  "tools": ["web_search", "memory_search", "memory_store", "send_message"],
  "limits": {
    "dailyTokenBudget": 300000,
    "monthlyTokenBudget": 6000000,
    "dailyTokensUsed": 18420,
    "monthlyTokensUsed": 412800
  },
  "sessionCount": 3,
  "cronJobCount": 2,
  "createdAt": "2026-01-15T09:00:00Z",
  "lastActiveAt": "2026-03-17T07:58:12Z"
}

PATCH /api/agents/:id 🔒 Auth required

Update an agent's configuration. Only include fields you want to change.

Request body

All fields are optional. Only the fields you include will be updated.

{
  "name": "Nova v2",
  "config": {
    "model": {
      "default": "claude-sonnet-4-20250514"
    },
    "limits": {
      "dailyTokenBudget": 500000
    }
  }
}

Response

Returns the updated agent object.

DELETE /api/agents/:id 🔒 Auth required

Delete an agent and all associated data.

Returns 204 No Content on success. This action is irreversible.

What gets deleted:

Agent configuration and SOUL file
All sessions and message history
Memory store contents
Cron job definitions (run history is retained in audit logs)

Agent status values

Status	Description
`provisioning`	Container is being initialized (10–30 seconds)
`online`	Agent is running and responsive
`degraded`	Running but with elevated latency or errors
`offline`	Gateway unreachable — container may have crashed
`paused`	Budget exhausted — will resume at next budget reset