COcoval
Agents

List agents

Retrieve a paginated list of agent configurations with optional filtering and sorting.

get/agents

Request

  • Base URL
    https://api.coval.dev/v1
  • Auth
    API key in header x-api-key

Query parameters

filterstring

Filter expression syntax.

Supported fields: model_type, display_name, create_time, update_time

Operators: =, !=, >, <, >=, <=, AND, OR

Values may be unquoted or double-quoted. Values containing spaces must be quoted (e.g., display_name="Support Agent").

Date format: ISO 8601 (e.g., 2025-10-01T00:00:00Z)

page_sizeinteger

Maximum number of results per page

page_tokenstring

Opaque pagination token from previous response.

Do not decode or modify this token.

order_bystring

Sort order specification.

Formats:

  1. Dash-prefix: -create_time (descending), display_name (ascending)
  2. Space-separated: create_time desc, display_name asc

Sortable fields: create_time, update_time, display_name, model_type

tag_filtersstring[]

Filter agents by tags. A resource matches when it has ALL the listed tags (AND-semantics).

Repeat the parameter for each tag (e.g., ?tag_filters=production&tag_filters=voice).

Response

Agents retrieved successfully

next_page_tokenstring nullable

Token for fetching next page (null if no more results)

Example response

{
  "agents": [
    {
      "id": "abc123def456ghi789jklm",
      "customer_agent_id": "my-support-agent",
      "display_name": "Customer Support Agent",
      "model_type": "MODEL_TYPE_VOICE",
      "phone_number": "+1234567890",
      "endpoint": "https://api.example.com/agent",
      "prompt": "You are a helpful customer support agent...",
      "language": "en",
      "attributes": {
        "company_name": "Acme Corp",
        "tier": "enterprise"
      },
      "metadata": {
        "voice": "alloy",
        "model": "gpt-realtime-2"
      },
      "workflows": {},
      "metric_ids": [
        "abc123def456ghi789jklm",
        "def456ghi789jklmabc123"
      ],
      "test_set_ids": [
        "gT5wq2Hn"
      ],
      "knowledge_base_ids": [],
      "tags": [
        "production",
        "voice"
      ],
      "create_time": "2025-10-14T12:00:00Z",
      "update_time": "2025-10-15T14:30:00Z"
    }
  ],
  "next_page_token": "eyJvZmZzZXQiOjUwfQ=="
}

Changes

No recorded changes to this operation across all 1 revision of this API.