---
title: "List AI agents"
method: GET
path: "/v3/ai-agents"
tags: ["v3", "ai-agents"]
---

# List AI agents

`GET /v3/ai-agents`

## Request

- Base URL: `https://api.mentium.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.mentium.io/v3/ai-agents`
- Auth: HTTP bearer

List AI agents for the current workspace with pagination and optional filters.

## Query parameters

- `page` integer: Page number
- `size` integer: Page size
- `search` string, nullable: Search by name or description
- `is_active` boolean, nullable: Filter by active status
- `sort_by` 'name' | 'model' | 'updated_at' | 'created_at': Sort field
- `sort_dir` 'asc' | 'desc': Sort direction

## Headers

- `mentium-workspace-id` string, nullable

## Response `200`

Successful Response

- AIAgentListResponse: Paginated response for listing AI agents.
  - `items` AIAgentResponse[], required
    - `id` string, required
    - `name` string, required
    - `description` string, nullable, required
    - `agent_type` string, required
    - `type_config` object, nullable, required
    - `workspace_phone_number_id` string, nullable
    - `model` string, required
    - `system_prompt_template` string, required
    - `user_prompt_template` string, nullable, required
    - `temperature` number, nullable, required
    - `max_tokens` integer, nullable, required
    - `reasoning_effort` string, nullable, required
    - `tools` string[], required
    - `tool_inputs` object, nullable: Agent-side default inputs per tool identifier (tool_identifier -> {param_key -> value}). Soft defaults that travel with the agent; runtime precedence is agent < node < LLM args.
    - `automation_tools_count` integer: Number of shared HTTP automation tools bound to this agent.
    - `is_active` boolean, required
    - `is_draft` boolean
    - `draft_of_id` string, nullable
    - `yaml_content` string, nullable
    - `chat_history` object[], nullable
    - `yaml_history` object[], nullable
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `prompt_variables` string[]: {{variable}} placeholder names found in the agent's prompts (system_prompt_template, user_prompt_template, type_config.first_message). Excludes ElevenLabs system variables (system__*) injected automatically at runtime.
    - `has_draft` boolean: True when the agent has unpublished draft changes.
    - `live_revision_id` string, nullable: The revision the agent runs
    - `draft` object, nullable: Staged draft changes that have not been published yet.
  - `total` integer, required
  - `page` integer, required
  - `size` integer, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/mentium/apis/mentium-api.md) - [All operations](https://skmtc.dev/mentium/apis/mentium-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mentium/apis/mentium-api/revisions/b4ed8e59432e?raw)