Agent Management

Overview

Agents are AI assistants that execute tasks within workspaces. Each agent has a specific role (ROUTA, CRAFTER, GATE, DEVELOPER) and can be configured with different model tiers for performance optimization.

Agent Roles

Role	Description
`ROUTA`	Orchestrator agent that coordinates other agents
`CRAFTER`	Specialized in crafting and refining content
`GATE`	Validation and quality control agent
`DEVELOPER`	Handles development and implementation tasks

Model Tiers

Tier	Description
`SMART`	Most capable models for complex reasoning
`BALANCED`	Balance between capability and speed
`FAST`	Fastest models for simple tasks

Agent Status

Status	Description
`PENDING`	Agent created but not started
`ACTIVE`	Agent is currently executing
`COMPLETED`	Agent finished successfully
`ERROR`	Agent encountered an error
`CANCELLED`	Agent was manually cancelled

List Agents

curl "http://localhost:3000/api/agents?workspaceId=default"

Endpoint

GET /api/agents

GET

List all agents in a workspace or get a single agent by ID

Query Parameters

workspaceId

string

required

The workspace ID to filter agents (defaults to "default")

string

If provided, returns a single agent instead of a list

summary

boolean

If present with id, returns agent summary (Next.js only)

role

string

Filter by agent role: ROUTA, CRAFTER, GATE, or DEVELOPER

status

string

Filter by status: PENDING, ACTIVE, COMPLETED, ERROR, or CANCELLED

parentId

string

Filter by parent agent ID

Response

agents

array

Array of agent objects (when listing)

When querying by ID, returns a single agent object directly.

Agent Object

string

required

Unique identifier for the agent

name

string

required

Display name of the agent

role

string

required

Agent role: ROUTA, CRAFTER, GATE, or DEVELOPER

modelTier

string

required

Model tier: SMART, BALANCED, or FAST

workspaceId

string

required

ID of the workspace this agent belongs to

parentId

string

ID of the parent agent (if this is a sub-agent)

status

string

required

Current status of the agent

metadata

object

required

Additional metadata as key-value pairs

createdAt

string

required

ISO 8601 timestamp of creation

updatedAt

string

required

ISO 8601 timestamp of last update

Response Example

{
  "agents": [
    {
      "id": "agent-abc123",
      "name": "Documentation Agent",
      "role": "DEVELOPER",
      "modelTier": "BALANCED",
      "workspaceId": "default",
      "parentId": null,
      "status": "ACTIVE",
      "metadata": {
        "specialty": "documentation"
      },
      "createdAt": "2026-03-03T10:00:00.000Z",
      "updatedAt": "2026-03-03T10:05:00.000Z"
    }
  ]
}

Create Agent

curl -X POST http://localhost:3000/api/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Documentation Agent",
    "role": "DEVELOPER",
    "workspaceId": "default",
    "modelTier": "BALANCED"
  }'

Endpoint

POST /api/agents

POST

Create a new agent

Request Body

name

string

required

Display name for the agent

role

string

required

Agent role: ROUTA, CRAFTER, GATE, or DEVELOPER

workspaceId

string

required

ID of the workspace (defaults to "default")

modelTier

string

Model tier: SMART, BALANCED, or FAST

parentId

string

ID of the parent agent (for creating sub-agents)

Response

agentId

string

required

ID of the newly created agent

agent

object

required

Complete agent object

Response Example

{
  "agentId": "agent-abc123",
  "agent": {
    "id": "agent-abc123",
    "name": "Documentation Agent",
    "role": "DEVELOPER",
    "modelTier": "BALANCED",
    "workspaceId": "default",
    "parentId": null,
    "status": "PENDING",
    "metadata": {},
    "createdAt": "2026-03-03T10:00:00.000Z",
    "updatedAt": "2026-03-03T10:00:00.000Z"
  }
}

Get Agent by ID

curl http://localhost:3000/api/agents/agent-abc123

Endpoint

GET /api/agents/{id}

GET

Get a single agent by ID (REST-style path parameter)

Path Parameters

string

required

The agent ID

Response

Returns a single agent object.

Status Codes

Status Code	Description
`200`	Success
`404`	Agent not found

Delete Agent

curl -X DELETE http://localhost:3000/api/agents/agent-abc123

Endpoint

DELETE /api/agents/{id}

DELETE

Delete an agent

Path Parameters

string

required

The agent ID to delete

Response

deleted

boolean

required

Always true when successful

Response Example

{
  "deleted": true
}

Update Agent Status

curl -X POST http://localhost:3000/api/agents/agent-abc123/status \
  -H "Content-Type: application/json" \
  -d '{"status": "ACTIVE"}'

Endpoint

POST /api/agents/{id}/status

POST

Update an agent’s status

Path Parameters

string

required

The agent ID

Request Body

status

string

required

New status: PENDING, ACTIVE, COMPLETED, ERROR, or CANCELLED

Response

updated

boolean

required

Always true when successful

Response Example

{
  "updated": true
}

Error Responses

400 Bad Request

{
  "error": "workspaceId is required"
}

404 Not Found

{
  "error": "Agent not found"
}

REST API

MCP Tools

ACP

A2A

Agent Management

Overview

Agent Roles

Model Tiers

Agent Status

List Agents

Endpoint

Query Parameters

Response

Agent Object

Response Example

Create Agent

Endpoint

Request Body

Response

Response Example

Get Agent by ID

Endpoint

Path Parameters

Response

Status Codes

Delete Agent

Endpoint

Path Parameters

Response

Response Example

Update Agent Status

Endpoint

Path Parameters

Request Body

Response

Response Example

Error Responses

400 Bad Request

404 Not Found

Build docs developers (and LLMs) love

REST API

MCP Tools

ACP

A2A

​Overview

​Agent Roles

​Model Tiers

​Agent Status

​List Agents

​Endpoint

​Query Parameters

​Response

​Agent Object

​Response Example

​Create Agent

​Endpoint

​Request Body

​Response

​Response Example

​Get Agent by ID

​Endpoint

​Path Parameters

​Response

​Status Codes

​Delete Agent

​Endpoint

​Path Parameters

​Response

​Response Example

​Update Agent Status

​Endpoint

​Path Parameters

​Request Body

​Response

​Response Example

​Error Responses

​400 Bad Request

​404 Not Found

Build docs developers (and LLMs) love

Overview

Agent Roles

Model Tiers

Agent Status

List Agents

Endpoint

Query Parameters

Response

Agent Object

Response Example

Create Agent

Endpoint

Request Body

Response

Response Example

Get Agent by ID

Endpoint

Path Parameters

Response

Status Codes

Delete Agent

Endpoint

Path Parameters

Response

Response Example

Update Agent Status

Endpoint

Path Parameters

Request Body

Response

Response Example

Error Responses

400 Bad Request

404 Not Found