> ## Documentation Index
> Fetch the complete documentation index at: https://guide.omnia-voice.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List voices

> Retrieve available voices for agent configuration.

Supports filtering by language, free-text search on the voice name,
sorting, and pagination. Voices are scoped to active entries by default.




## OpenAPI

````yaml /openapi.yaml get /voices
openapi: 3.0.0
info:
  title: Omnia Voice API
  description: >
    The Omnia Voice API allows you to programmatically manage voice agents,
    tools, phone numbers, and call logs.


    ## Authentication

    All API requests require an API key to be passed in the `X-API-Key` header.


    ## Rate Limiting

    API requests are rate limited to 1000 requests per hour per API key.
  version: 1.0.0
  contact:
    email: support@omnia-voice.com
servers:
  - url: https://api.omnia-voice.com/api/v1
    description: Production
  - url: https://dashboard.omnia-voice.com/api/v1
    description: Production (alias — same service)
security:
  - ApiKeyAuth: []
tags:
  - name: Agents
    description: Manage voice agents
  - name: Tools
    description: Manage agent tools and actions
  - name: Phone Numbers
    description: Manage phone number assignments
  - name: Calls
    description: Create and manage voice calls
  - name: Call Logs
    description: View call history and details
  - name: Pricing
    description: Get pricing information and calculate call costs
  - name: Configuration
    description: Get configuration options (voices, languages)
paths:
  /voices:
    get:
      tags:
        - Configuration
      summary: List voices
      description: |
        Retrieve available voices for agent configuration.

        Supports filtering by language, free-text search on the voice name,
        sorting, and pagination. Voices are scoped to active entries by default.
      operationId: listVoices
      parameters:
        - name: languageCode
          in: query
          schema:
            type: string
          description: |
            Filter by exact language code, e.g. `en`, `en-GB`, `pt-BR`.
            Use `GET /languages` to discover valid codes.
        - name: isActive
          in: query
          schema:
            type: boolean
          description: Filter by active status. Defaults to `true` when omitted.
        - name: search
          in: query
          schema:
            type: string
          description: Case-insensitive substring match on the voice name.
        - name: sortBy
          in: query
          schema:
            type: string
            enum:
              - name
              - languageCode
            default: languageCode
          description: Field to sort results by.
        - name: sortDir
          in: query
          schema:
            type: string
            enum:
              - asc
              - desc
            default: asc
          description: Sort direction.
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 100
          description: Maximum number of voices to return.
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Number of voices to skip (for pagination).
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Voice'
                  groupedByLanguage:
                    type: object
                    description: >
                      Convenience grouping of the returned page by
                      `languageCode`.

                      Each entry contains a subset of `Voice` fields suitable
                      for

                      rendering grouped pickers.
                    additionalProperties:
                      type: array
                      items:
                        $ref: '#/components/schemas/Voice'
                  total:
                    type: integer
                    description: Total number of voices matching the filters (unpaged).
                  pagination:
                    type: object
                    properties:
                      total:
                        type: integer
                        description: Same as the top-level `total`.
                      limit:
                        type: integer
                      offset:
                        type: integer
                      returned:
                        type: integer
                        description: Number of voices in this response page.
components:
  schemas:
    Voice:
      type: object
      properties:
        id:
          type: string
          description: Voice ID
        name:
          type: string
          description: Voice name
        description:
          type: string
          nullable: true
          description: Voice description
        previewUrl:
          type: string
          nullable: true
          description: Audio preview URL
        languageCode:
          type: string
          description: >
            BCP-47 language code for this voice. May be a base code (e.g. `en`,
            `de`)

            or a regional variant (e.g. `en-GB`, `pt-BR`, `ar-SA`).
        gender:
          type: string
          nullable: true
          description: Voice gender, when available (e.g. `male`, `female`).
        isActive:
          type: boolean
          description: Whether the voice is currently selectable.
        language:
          type: object
          description: Resolved language metadata for `languageCode`.
          properties:
            code:
              type: string
              description: Same as `languageCode`.
            name:
              type: string
              description: Human-readable language name (e.g. `English (UK)`).
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication

````