List agents

GET /api/v1/agents

Returns the agents in your organization, paginated.

Authentication

X-API-Key: zsk_...

Query parameters

Param	Type	Default	Notes
`limit`	int (`1..100`)	`50`	Items per page.
`offset`	int (`≥0`)	`0`	Offset-based pagination.
`status`	string	`"active"`	One of `active`, `archived`.

Response

Each item is an AgentEnvelope (same shape returned by GET /agents/{agent_uuid}):

{
  "agents": [
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "status": "active",
      "createdAt": "2026-06-01T10:00:00Z",
      "updatedAt": "2026-06-16T09:30:00Z",
      "config": {
        "name": "Sales bot",
        "description": "Qualifies inbound leads.",
        "languages": ["en"],
        "systemPrompt": "You are...",
        "timezone": "Asia/Kolkata",
        "greeting": { "firstMessages": ["Hi, can I help you?"], "interruptible": false, "speakFirst": "agent", "agentDelayS": 0.0, "userTimeoutS": 3.0 },
        "llm": { "provider": "openai", "model": "gpt-5.4-mini", "temperature": 1.0, "maxTokens": 251, "prewarm": true },
        "stt": { "provider": "soniox", "model": null, "interruptionMinWords": 0, "...": "per-provider tuning blocks" },
        "tts": { "provider": "elevenlabs", "model": null, "voice": null, "...": "per-provider tuning blocks" },
        "maxCallDurationS": 610,
        "userIdleTimeoutS": 7,
        "userIdleMessages": ["Are you still there?"],
        "userIdleMaxRetries": 2,
        "tools": [
          "abc12345-6789-0123-4567-89abcdef0123",
          { "type": "endCall", "name": "end_call", "description": "…", "config": { "messageType": "custom", "customMessages": ["Goodbye!"], "audioRecordingId": null } }
        ],
        "voicemailDetection": true,
        "webhook": null,
        "...": "noiseGate, human-feel audio, summarization, contextVariables — see the schema page"
      }
    }
  ],
  "total": 7,
  "limit": 50,
  "offset": 0
}

Field	Notes
`uuid`	The agent's identifier — used in every CRUD path and as `agentId` in `POST /call`.
`status`	`"active"` or `"archived"`.
`config`	The full validated Agent Config (camelCase).
`config.tools`	Mixed array of saved-tool UUID strings and inline tool objects; the `endCall` tool is always present.
`config.webhook`	`null` or `{ "url": "…", "headers": { … } }`. The write-only `webhookSecret` is never returned.
`total` / `limit` / `offset`	Pagination — total matching rows, plus the echoed page window.

curl "https://dashboard.zoxa.ai/api/v1/agents?limit=20&offset=0&status=active" \
  -H "X-API-Key: zsk_..."

const params = new URLSearchParams({ limit: "20", offset: "0", status: "active" });
const res = await fetch(`https://dashboard.zoxa.ai/api/v1/agents?${params}`, {
  headers: { "X-API-Key": "zsk_..." },
});
const { agents, total } = await res.json();

import httpx
resp = httpx.get(
    "https://dashboard.zoxa.ai/api/v1/agents",
    headers={"X-API-Key": "zsk_..."},
    params={"limit": 20, "offset": 0, "status": "active"},
)
print(resp.json()["total"])

Errors

Status	When
`400`	No organization selected on the API key.
`422`	`limit` / `offset` out of range, or invalid `status`.

POST /agents — create
GET /agents/{agent_uuid} — single agent
Agent config schema — full field reference

Authentication

Query parameters

Response

Errors

Related

On this page