> ## Documentation Index > Fetch the complete documentation index at: https://docs.truedy.ai/llms.txt > Use this file to discover all available pages before exploring further. # List Agents > Retrieve all voice AI agents in your organization with optional filtering. ## OpenAPI ````yaml /api-reference/openapi.json get /agents openapi: 3.1.0 info: title: Truedy API description: >- Truedy Public API - Build voice AI agents and make automated phone calls. ## Authentication All requests require **Authorization: Bearer **. Get your API key from the [Truedy Dashboard](https://app.truedy.ai). ## Response Format All successful responses follow this format: ```json { "data": { /* resource or list of resources */ }, "meta": { "request_id": "req_xxx", "ts": "2026-03-03T20:30:21.310278Z" }, "pagination": { /* optional, for list endpoints */ } } ``` ## Error Handling Errors return appropriate HTTP status codes with structured error messages. Always check the `error` field in the response body for details. version: 1.0.0 servers: - url: https://api.truedy.ai/api/public/v1 description: Truedy Public API security: - BearerAuth: [] paths: /agents: get: tags: - Agents summary: List Agents description: >- Retrieve all voice AI agents in your organization with optional filtering. operationId: list_agents parameters: - name: status in: query required: false description: Filter by status (active, draft) schema: type: string enum: - active - draft - name: name in: query required: false description: Filter by name (substring, case-insensitive) schema: type: string - name: limit in: query required: false description: Maximum results per page (1-100) schema: type: integer minimum: 1 maximum: 100 default: 50 - name: offset in: query required: false description: Number of results to skip schema: type: integer minimum: 0 default: 0 responses: '200': description: List of agents content: application/json: schema: type: object required: - data - meta properties: data: type: array items: $ref: '#/components/schemas/AgentResponse' meta: $ref: '#/components/schemas/ResponseMeta' pagination: $ref: '#/components/schemas/PaginationInfo' examples: success: value: data: - id: agt_f9447372 name: Customer Support Agent description: AI-powered customer support status: active voice_id: voice_c7d82fec voice_name: Sarah system_prompt: You are a helpful customer support agent. model: ultravox-v0.7 tools: [] knowledge_bases: [] created_at: '2026-03-03T20:30:21.310278Z' updated_at: '2026-03-03T20:30:21.310278Z' meta: request_id: req_32e7531c-8 ts: '2026-03-03T20:30:21.310278Z' pagination: total: 5 limit: 50 offset: 0 has_more: false example: data: - id: agt_f9447372 name: Customer Support Agent description: Handles inbound support inquiries status: active model: ultravox-v0.7 voice_id: voice_c7d82fec voice_name: Sarah system_prompt: >- You are a helpful customer support agent. Be friendly and professional. greeting: Hello! Thanks for calling. How can I help you today? inactivity_message: Are you still there? Take your time. inactivity_timeout: 30 max_duration: 1800 tools: - tool_p1q2r3s4 knowledge_base_ids: - kb_x9y8z7w6 created_at: '2026-03-15T09:00:00Z' updated_at: '2026-04-01T14:30:00Z' - id: agt_b2c3d4e5 name: Sales Agent description: Handles inbound support inquiries status: active model: ultravox-v0.7 voice_id: voice_c7d82fec voice_name: Sarah system_prompt: >- You are a helpful customer support agent. Be friendly and professional. greeting: Hello! Thanks for calling. How can I help you today? inactivity_message: Are you still there? Take your time. inactivity_timeout: 30 max_duration: 1800 tools: - tool_p1q2r3s4 knowledge_base_ids: - kb_x9y8z7w6 created_at: '2026-03-15T09:00:00Z' updated_at: '2026-04-01T14:30:00Z' meta: request_id: req_32e7531c ts: '2026-04-05T10:22:00Z' pagination: total: 24 limit: 50 offset: 0 has_more: false '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: error: value: error: code: unauthorized message: Invalid or missing API key details: reason: 'The Authorization: Bearer header is required' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: error: value: error: code: rate_limit_exceeded message: Too many requests details: limit: 100 remaining: 0 reset_at: '2026-03-03T20:30:21.310278Z' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: AgentResponse: type: object required: - id - name - voice_id - status - model - created_at - updated_at properties: id: type: string description: Unique agent identifier example: agt_f9447372 name: type: string description: Display name of the agent example: Customer Support Agent description: description: Optional description of the agent's purpose example: Handles customer inquiries and support requests type: - string - 'null' voice_id: type: string description: ID of the voice used for this agent example: voice_c7d82fec voice_name: description: Resolved voice display name example: Sarah type: - string - 'null' system_prompt: description: System prompt defining agent behavior and personality example: >- You are a helpful customer support agent. Be friendly and professional. type: - string - 'null' model: type: string description: AI model identifier example: ultravox-v0.7 tools: type: array items: type: string description: List of tool IDs attached to the agent example: - tool_abc123 - tool_def456 knowledge_bases: type: array items: type: string description: List of knowledge base IDs attached to the agent example: - kb_xyz789 status: type: string enum: - active - draft description: Agent status example: active temperature: minimum: 0 maximum: 1 description: LLM temperature controlling randomness (0=deterministic, 1=creative) example: 0.7 type: - number - 'null' language_hint: description: BCP47 language code for speech recognition example: en-US type: - string - 'null' recording_enabled: description: Whether call recording is enabled example: true type: - boolean - 'null' join_timeout: description: Timeout for the callee to answer (e.g., 30s) example: 30s type: - string - 'null' max_duration: description: Maximum call duration (e.g., 3600s for 1 hour) example: 3600s type: - string - 'null' created_at: type: string format: date-time description: When the agent was created example: '2026-03-03T20:30:21.310278Z' updated_at: type: string format: date-time description: When the agent was last updated example: '2026-03-03T20:30:21.310278Z' ResponseMeta: type: object required: - request_id - ts properties: request_id: type: string description: Unique request identifier for debugging and support example: req_32e7531c-8 ts: type: string format: date-time description: Server timestamp when the response was generated example: '2026-03-03T20:30:21.310278Z' PaginationInfo: type: object required: - total - limit - offset - has_more properties: total: type: integer description: Total number of items matching the query example: 156 limit: type: integer description: Maximum items returned per page example: 50 offset: type: integer description: Number of items skipped from the beginning example: 0 has_more: type: boolean description: Whether more items exist after this page example: true ErrorResponse: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: Error code example: not_found message: type: string description: Human-readable error message example: The requested resource does not exist details: description: Additional error context example: resource: agent id: agt_invalid type: - object - 'null' securitySchemes: BearerAuth: type: http scheme: bearer description: >- API key authentication. Include your API key in the Authorization header: Bearer ````