List Agents

Retrieve all agents in the organization

GET /v1/agents

Retrieve all agents in the organization. Returns both active and archived agents.

Query Parameters

No query parameters. This endpoint returns all agents without pagination.

Response

Returns a wrapper object with the agent array.

data · array

Array of agent objects

total · integer

Total count of agents

Agent Object Fields

id · string

UUID of the agent

name · string

Agent name

system_prompt · string

Base system prompt

description · string

Optional description

default_model_id · string

UUID of default model (null if not set)

capabilities · array

Array of capability references

status · string

Agent status: active or archived

created_at · string

ISO 8601 timestamp of creation

updated_at · string

ISO 8601 timestamp of last update

Example Request

curl http://localhost:9300/v1/agents

Example Response

{
  "data": [
    {
      "id": "01933b5a-0000-7000-8000-000000000001",
      "name": "Research Assistant",
      "system_prompt": "You are a helpful research assistant.",
      "description": "General purpose research agent",
      "default_model_id": "01933b5a-0000-7000-8000-000000000010",
      "capabilities": ["current_time", "web_fetch"],
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "01933b5a-0000-7000-8000-000000000002",
      "name": "Code Assistant",
      "system_prompt": "You are an expert coding assistant.",
      "description": null,
      "default_model_id": null,
      "capabilities": ["session_file_system"],
      "status": "active",
      "created_at": "2024-01-15T11:00:00Z",
      "updated_at": "2024-01-15T11:00:00Z"
    }
  ],
  "total": 2
}

This endpoint returns all agents without pagination. If you need to filter agents, you can do so client-side after retrieving the list.

Filtering by Status

To list only active agents, filter the response client-side:

const response = await fetch('http://localhost:9300/v1/agents');
const { data } = await response.json();
const activeAgents = data.filter(agent => agent.status === 'active');