> ## Documentation Index > Fetch the complete documentation index at: https://docs.talkpilot.io/llms.txt > Use this file to discover all available pages before exploring further. # List agents > Returns all agents accessible to the API key. If the key has `allowed_agent_ids` set, only those agents are returned. ## OpenAPI ````yaml get /v1/agents openapi: 3.1.0 info: title: TalkPilot API version: 1.0.0 description: > The TalkPilot API allows you to programmatically manage your call center agents, employees, forwarding slots, knowledge base, and more. ## Authentication All API requests require an API key passed via the `X-API-Key` header: ``` X-API-Key: tp_live_abc123def456... ``` An API key can reach every organization its creator is a member of (see `GET /v1/organization`) and can be restricted to specific agents and permissions. Create and manage keys in the TalkPilot Dashboard under **Settings > API** (Dev-Admin only). ## Rate Limiting Default limits per API key: **60 requests/minute** and **1,000 requests/hour** (both enforced, both configurable per key). Rate limit headers are included in every response to a request authenticated with an API key (Dashboard JWT requests are not rate limited): - `X-RateLimit-Limit` — Max requests per minute - `X-RateLimit-Remaining` — Remaining requests in the current minute window - `X-RateLimit-Reset` — Unix timestamp roughly 60 seconds in the future When rate limited, the API returns `429 Too Many Requests` with `Retry-After: 60` (minute window) or `Retry-After: 3600` (hour window). ## Pagination List endpoints support pagination via query parameters: - `page` — Page number (default: 1) - `limit` — Items per page (default: 20, max: 100) Paginated responses include a `pagination` object with `page`, `limit`, `total`, and `pages`. ## Error Format All errors follow a consistent format: ```json { "error": { "code": "VALIDATION_ERROR", "message": "Human-readable description", "details": [{ "field": "name", "message": "Required" }], "request_id": "req_abc123" } } ``` contact: name: TalkPilot Support email: support@talkpilot.io license: name: Proprietary identifier: LicenseRef-Proprietary servers: - url: https://api.talkpilot.io description: Production security: - apiKey: [] tags: - name: Health description: API health and status - name: Agents description: Manage AI agent configurations - name: Workflow description: Multi-state conversation flow of an agent - name: Tools description: Manage agent tools (HTTP requests, call transfers, etc.) - name: Employees description: Manage employees linked to agents - name: Contacts description: >- Customer contacts (customer_database) per agent — the voice agent recognises callers and greets them by name or tag from here - name: Forwarding Slots description: Manage call forwarding slot assignments - name: Knowledge Base description: Manage agent knowledge base documents - name: Calls description: Read call records and transcripts - name: Organization description: Organization-level settings - name: API Keys description: Manage API keys (Dashboard JWT auth only; dev_admin) paths: /v1/agents: get: tags: - Agents summary: List agents description: | Returns all agents accessible to the API key. If the key has `allowed_agent_ids` set, only those agents are returned. operationId: listAgents parameters: - $ref: '#/components/parameters/PageParam' - $ref: '#/components/parameters/LimitParam' responses: '200': description: List of agents content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Agent' pagination: $ref: '#/components/schemas/Pagination' example: data: - id: 550e8400-e29b-41d4-a716-446655440000 name: Rezeption Bot phone_number: '+4930123456' is_active: true language: de llm_provider: openai llm_model: gpt-4.1 voice_id: sarah created_at: '2025-06-01T10:00:00Z' pagination: page: 1 limit: 20 total: 3 pages: 1 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' components: parameters: PageParam: name: page in: query description: Page number schema: type: integer minimum: 1 default: 1 LimitParam: name: limit in: query description: Items per page schema: type: integer minimum: 1 maximum: 100 default: 20 schemas: Agent: type: object properties: id: type: string format: uuid organization_id: type: string format: uuid readOnly: true name: type: string phone_number: type: string is_active: type: boolean language: type: - string - 'null' description: 'Language code: de, en, fr, es' formality: type: - string - 'null' enum: - formal - informal description: formal = Sie, informal = Du llm_provider: type: - string - 'null' enum: - azure - openai - gemini - gemini_live - gemini_live_cascade - openai_realtime - openai_realtime_cascade - groq llm_model: type: - string - 'null' description: >- Model identifier, e.g. gpt-4.1, gemini-2.5-flash, meta-llama/llama-4-scout-17b-16e-instruct, llama-3.3-70b-versatile, llama-3.1-8b-instant llm_temperature: type: - number - 'null' minimum: 0 maximum: 2 tts_provider: type: - string - 'null' enum: - cartesia - elevenlabs - gemini_live - openai_realtime voice_id: type: - string - 'null' description: Voice identifier for TTS realtime_voice: type: - string - 'null' description: Voice for native realtime providers (OpenAI/Gemini) speaking_rate: type: - number - 'null' minimum: 0.5 maximum: 2 stt_provider: type: - string - 'null' enum: - deepgram - elevenlabs - mistral - groq description: Speech-to-text provider (null for native realtime) stt_keywords: type: - array - 'null' maxItems: 100 items: type: string description: Words the speech recognizer should prefer (names, products); max 100 prompt: type: string description: System prompt for the agent maxLength: 50000 greeting: type: - string - 'null' description: Initial greeting message when call starts maxLength: 2000 greeting_variants: type: - array - 'null' items: $ref: '#/components/schemas/GreetingVariant' description: > Personalised greetings. The first variant whose conditions all match the caller wins; otherwise `greeting` is spoken. A variant is only spoken when every placeholder in it has a value. post_call_webhook_url: type: - string - 'null' format: uri description: Webhook URL called after each call completes schedule: $ref: '#/components/schemas/AgentSchedule' backup_agent_id: type: - string - 'null' format: uuid description: Fallback agent when outside the schedule allow_greeting_interruption: type: - boolean - 'null' description: Allow callers to interrupt the greeting short_calls_auto_edit: type: boolean description: Automatically mark very short calls as done track_caller_name: type: boolean description: Ask for and track the caller's name transfer_timeout_seconds: type: - integer - 'null' minimum: 5 maximum: 45 description: Timeout in seconds for call transfers (5-45) bundesland: $ref: '#/components/schemas/Bundesland' background_audio_enabled: type: boolean description: Play ambient background audio during the call background_audio_type: $ref: '#/components/schemas/BackgroundAudioType' background_audio_volume: type: number minimum: 0 maximum: 1 thinking_sound_enabled: type: boolean description: Play a subtle sound while the agent waits for the LLM thinking_sound_volume: type: number minimum: 0 maximum: 1 aic_enhancement_enabled: type: boolean description: >- On-device voice-focus enhancement (ai-coustics) before speech recognition retention_days: type: - integer - 'null' readOnly: true description: >- GDPR retention of call data in days (null = default 90). Managed in the Dashboard metadata: type: - object - 'null' readOnly: true description: >- Provider-specific tuning (e.g. Flux/EOU settings). Managed in the Dashboard created_at: type: string format: date-time updated_at: type: string format: date-time Pagination: type: object properties: page: type: integer limit: type: integer total: type: integer pages: type: integer GreetingVariant: type: object required: - greeting description: > Needs `greeting` plus at least one condition (`tag`, a time window `from`+`to`, or `min_calls_today`). Several conditions are combined with AND; the order of the variants is the priority. Unknown keys are rejected. properties: greeting: type: string description: >- May use {{vorname}}, {{nachname}}, {{anrede}} (from the contact) and pre-call webhook variables tag: type: string description: >- A tag of the caller's contact (customer database), compared case-insensitively from: type: string pattern: ^([01]\d|2[0-3]):[0-5]\d$ description: >- Start of the time window, HH:MM Europe/Berlin (inclusive). Requires `to` to: type: string pattern: ^([01]\d|2[0-3]):[0-5]\d$ description: >- End of the time window (exclusive). `from` > `to` wraps past midnight min_calls_today: type: integer minimum: 1 description: Caller has already called at least this many times today AgentSchedule: type: - object - 'null' description: | Agent business hours. When set, the agent only accepts calls during the specified time windows. Outside hours, calls go to the backup agent. properties: timezone: type: string description: IANA timezone identifier example: Europe/Berlin rules: type: array items: type: object required: - days - start_time - end_time properties: days: type: array items: type: integer minimum: 0 maximum: 6 description: Days of week (0=Sunday, 1=Monday, ..., 6=Saturday) example: - 1 - 2 - 3 - 4 - 5 start_time: type: string pattern: ^\d{2}:\d{2}$ description: Start time in HH:mm example: '08:00' end_time: type: string pattern: ^\d{2}:\d{2}$ description: End time in HH:mm example: '18:00' Bundesland: type: string enum: - DE - BW - BY - BE - BB - HB - HH - HE - MV - NI - NW - NRW - RP - SL - SN - ST - SH - TH description: German state for public-holiday handling; DE = nationwide holidays only BackgroundAudioType: type: string enum: - office - cafe - home_office Error: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: string enum: - VALIDATION_ERROR - UNAUTHORIZED - FORBIDDEN - AGENT_NOT_ACCESSIBLE - NOT_FOUND - CONFLICT - RATE_LIMITED - INTERNAL_ERROR message: type: string details: type: array items: type: object properties: field: type: string message: type: string request_id: type: string responses: Unauthorized: description: Missing or invalid authentication content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: Invalid or missing API key request_id: req_abc123 Forbidden: description: > Insufficient permissions (`FORBIDDEN`), or the agent is outside the key's `allowed_agent_ids` (`AGENT_NOT_ACCESSIBLE`) content: application/json: schema: $ref: '#/components/schemas/Error' examples: missingPermission: value: error: code: FORBIDDEN message: 'API key lacks required permission: agents:write' request_id: req_abc123 agentNotAccessible: value: error: code: AGENT_NOT_ACCESSIBLE message: API key does not have access to this agent request_id: req_abc123 RateLimited: description: Too many requests for this API key (60/minute or 1,000/hour by default) headers: Retry-After: description: >- Seconds to wait before retrying — 60 for the minute window, 3600 for the hour window schema: type: integer X-RateLimit-Limit: schema: type: integer X-RateLimit-Remaining: schema: type: integer X-RateLimit-Reset: schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: RATE_LIMITED message: Rate limit exceeded. Try again in 60 seconds. request_id: req_abc123 securitySchemes: apiKey: type: apiKey in: header name: X-API-Key description: | API key for external access. Format: `tp_live_<32-hex-chars>`. Create keys in the TalkPilot Dashboard under Settings > API. ````