API Reference
List Agents
GET /api/v1/agents — paginated list of agents in your organization or project.
Returns a paginated list of agents visible to your API key.
GET /api/v1/agentsQuery parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
page | integer | No | Page number, 1-indexed. Default 1. |
limit | integer | No | Results per page, max 100. Default 20. |
status | string | No | Filter by agent status: draft, active, or archived. |
project_ref_id | string (UUID) | No | Filter to one project. Org-scoped keys only — ignored for project-scoped keys, which always see only their own project. |
Response
200 OK
{
"data": [
{
"agentId": "3f9c1a2e-...",
"name": "Support Bot",
"description": "Handles Tier 1 support tickets",
"status": "active",
"projectId": null,
"config": { "...": "full agent config object" },
"configSchemaVersion": 1,
"createdAt": "2026-06-01T12:00:00.000Z",
"updatedAt": "2026-06-15T09:30:00.000Z"
}
],
"total": 1,
"page": 1,
"limit": 20
}Errors
| Status | error | When |
|---|---|---|
400 | validation error ({ "errors": [...] }) | page/limit/status/project_ref_id fails validation |
422 | project_not_found | project_ref_id doesn't belong to your organization |
Example
curl "https://api.elizon.com/api/v1/agents?status=active&limit=50" \
-H "X-API-Key: elz_your_key_here"