Skip to main content

​
Agents API

These endpoints power the Agent History sidebar and the persistence layer. All endpoints are internal Next.js API routes.

​
List agents

GET /api/agents
Returns all non-archived agents sorted by updated_at descending. Response 
[
  {
    "id": "abc123",
    "name": "Customer Support Agent",
    "createdAt": 1710000000000,
    "updatedAt": 1710001000000
  }
]

​
Create agent

POST /api/agents
Creates a new agent with an initial version snapshot. Body 
{
  "name": "My Agent",
  "flow": { "nodes": [], "edges": [] }
}
Response — the created agent object including the generated id.

​
Get agent

GET /api/agents/:id
Returns the agent metadata and its latest version snapshot.

​
Update agent

PATCH /api/agents/:id
Renames an agent or saves a new version snapshot. Body (all fields optional) 
{
  "name": "New Name",
  "flow": { "nodes": [], "edges": [] }
}

​
Delete agent

DELETE /api/agents/:id
Soft-deletes (archives) the agent. It is hidden from the list but retained in the database.

​
AI Builder conversation history

GET /api/agents/:id/conversations
Returns the stored AI Builder chat history for the given agent (role, content, operations, node attachments).

​
List test sessions

GET /api/agents/:id/test-sessions
Returns all test sessions for the agent, sorted by started_at descending. Response 
[
  {
    "id": "sess_xyz",
    "startedAt": 1710000000000,
    "endedAt": 1710000300000,
    "durationMs": 300000,
    "roomName": "room-abc",
    "sessionType": "test"
  }
]

​
Get / update test session

GET  /api/agents/:id/test-sessions/:sessionId
PATCH /api/agents/:id/test-sessions/:sessionId
PATCH accepts endedAt and durationMs to close a session.

​
Session messages

GET  /api/agents/:id/test-sessions/:sessionId/messages
POST /api/agents/:id/test-sessions/:sessionId/messages
POST body: 
{
  "role": "user",
  "content": "Hello!",
  "stepId": "start",
  "timestamp": 1710000001000
}

​
List deploys

GET /api/agents/:id/deploys
Returns all deploy records for the agent (status, subdomain, deploy number, timestamps).