API REFERENCE
Agents API
The Agents API lets you create, retrieve, update, and delete agents. Agents are the core resource — each agent has a model, system prompt, tools, and configuration.
The Agent Object
Agent object
{
"id": "agt_abc123def456",
"name": "Support Agent",
"model": "claude-sonnet-4-20250514",
"systemPrompt": "You are a helpful customer support agent...",
"status": "active",
"tools": [
{
"name": "lookup_order",
"description": "Look up an order by ID",
"parameters": { "type": "object", "properties": { ... } },
"handler": "https://api.example.com/webhooks/orders"
}
],
"parameters": {
"temperature": 0.3,
"maxTokens": 1024,
"topP": 0.9
},
"memory": {
"enabled": true,
"maxTurns": 50,
"summarize": true
},
"metadata": {
"team": "support",
"version": "1.0"
},
"createdAt": "2026-03-15T10:30:00Z",
"updatedAt": "2026-03-15T10:30:00Z"
}
Create an Agent
POST /v1/agents
Request
{
"name": "Support Agent",
"model": "claude-sonnet-4-20250514",
"systemPrompt": "You are a helpful customer support agent...",
"tools": [],
"parameters": {
"temperature": 0.3,
"maxTokens": 1024
},
"memory": {
"enabled": true,
"maxTurns": 50
},
"metadata": {}
}
FieldRequiredDescription
nameYesDisplay name for the agent (1-100 chars)
modelYesModel ID: claude-sonnet-4-20250514, claude-haiku-4-20250514, or claude-opus-4-20250514
systemPromptYesInstructions defining the agent's behavior
toolsNoArray of tool definitions
parametersNoGeneration parameters (temperature, maxTokens, topP)
memoryNoMemory configuration object
templateNoPre-built template ID (overrides systemPrompt)
metadataNoCustom key-value pairs (max 16 keys)
Response (201)
{
"id": "agt_abc123def456",
"name": "Support Agent",
"model": "claude-sonnet-4-20250514",
"status": "active",
...
}
List Agents
GET /v1/agents
Returns a paginated list of agents. Supports filtering by status and name.
Query parameters
GET /v1/agents?status=active&limit=20&after=agt_abc123
Response (200)
{
"data": [
{ "id": "agt_abc123", "name": "Support Agent", ... },
{ "id": "agt_def456", "name": "Sales Bot", ... }
],
"hasMore": true,
"nextCursor": "agt_ghi789"
}
Retrieve an Agent
GET /v1/agents/:id
Response (200)
{
"id": "agt_abc123def456",
"name": "Support Agent",
"model": "claude-sonnet-4-20250514",
"systemPrompt": "...",
"status": "active",
"tools": [...],
"parameters": { ... },
"memory": { ... },
"metadata": { ... },
"createdAt": "2026-03-15T10:30:00Z",
"updatedAt": "2026-03-15T10:30:00Z"
}
Update an Agent
PATCH /v1/agents/:id
Only include the fields you want to update. Omitted fields are unchanged.
Request
{
"systemPrompt": "Updated instructions...",
"parameters": {
"temperature": 0.5
},
"status": "paused"
}
Delete an Agent
DELETE /v1/agents/:id
Permanently deletes the agent and all associated conversations. This action cannot be undone.
Response (200)
{
"id": "agt_abc123def456",
"deleted": true
}