> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getsupervisor.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Voces disponibles

> Consulta el catálogo de voces del workspace con GET /v1/catalogs/items.

<Note>
  Las voces no tienen endpoint propio: viven en el catálogo, junto con idiomas,
  tonos, estilos de mensaje, etiquetas y eventos de webhook. Se consultan
  filtrando por tipo en <code>GET /v1/catalogs/items</code>.
</Note>

<Info>
  Requiere permiso <code>catalogs:read</code> y el header{' '}
  <code>X-Workspace-Id</code>. El catálogo mezcla los ítems globales con los
  propios del workspace.
</Info>

## Tipos de ítem

El campo `type` acepta un conjunto cerrado de valores:

| `type`          | Qué contiene                                    |
| --------------- | ----------------------------------------------- |
| `voice`         | Voces de los proveedores configurados           |
| `language`      | Idiomas y variantes regionales                  |
| `tone_style`    | Tonos de conversación                           |
| `message_style` | Estilos de redacción del mensaje                |
| `tag`           | Etiquetas de clasificación                      |
| `webhook_event` | Eventos a los que un webhook se puede suscribir |

## Listar las voces

El filtro se escribe con la gramática del query builder: `eq(type,"voice")`.

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url "$API_BASE_URL/v1/catalogs/items?filter=eq(type,%22voice%22)&limit=50" \
    --header "X-API-Key: $API_KEY" \
    --header "X-Workspace-Id: $WORKSPACE_ID"
  ```

  ```ts TypeScript theme={null}
  const response = await fetch(
    `${process.env.API_BASE_URL}/v1/catalogs/items?` +
      new URLSearchParams({
        filter: 'eq(type,"voice")',
        limit: '50',
      }),
    {
      headers: {
        'X-API-Key': process.env.API_KEY!,
        'X-Workspace-Id': process.env.WORKSPACE_ID!,
      },
    },
  );

  const { data, meta } = await response.json();
  console.log(meta.total, data[0]?.name);
  ```
</CodeGroup>

## Respuesta

```json theme={null}
{
  "data": [
    {
      "id": "3f7c1d02-9b44-4a1e-8f30-5b6e2c9a7d11",
      "type": "voice",
      "systemIdentifier": "elevenlabs.rachel",
      "scope": "global",
      "workspaceId": null,
      "name": "Rachel (ElevenLabs)",
      "description": "Voz femenina multilingüe con acento estadounidense.",
      "isActive": true,
      "metadata": {
        "provider": "elevenlabs",
        "voiceId": "21m00Tcm4TlvDq8ikWAM",
        "gender": "female"
      },
      "createdAt": "2026-01-08T12:00:00.000Z",
      "updatedAt": "2026-01-08T12:00:00.000Z",
      "links": {
        "self": "/v1/catalogs/items/3f7c1d02-9b44-4a1e-8f30-5b6e2c9a7d11",
        "catalog": "/v1/catalogs/items"
      }
    }
  ],
  "meta": {
    "total": 12,
    "page": 1,
    "limit": 50,
    "hasNext": false,
    "hasPrevious": false,
    "sort": ["createdAt"],
    "appliedFilters": { "type": "voice" }
  }
}
```

Los atributos que varían por proveedor —`voiceId`, género, acento— viajan en
`metadata`, así que conviene leerlos de ahí y no asumir columnas fijas.

## Combinar filtros

<CodeGroup>
  ```text Voces activas theme={null}
  filter=and(eq(type,"voice"),eq(isActive,true))
  ```

  ```text Sólo las del workspace theme={null}
  filter=and(eq(type,"voice"),eq(scope,"workspace"))
  ```

  ```text Buscar por nombre theme={null}
  filter=eq(type,"voice")&q=rachel
  ```
</CodeGroup>

<Warning>
  Los parámetros `include` y `fields` no están soportados por el query builder;
  las respuestas siempre traen el objeto completo. Para paginar se usan `page`
  (desde 1) y `limit` (máximo 100), y para ordenar `sort`, con `-` como prefijo
  para descendente.
</Warning>

## Con el SDK de TypeScript

El SDK trae un atajo que hace este filtrado y normaliza cada ítem a una forma de
voz, así que no hay que armar el `filter` a mano:

```ts theme={null}
const voices = await client.voices.list({
  gender: 'female',
  locale: 'es-MX',
  limit: 20,
});

console.log(voices.meta.total, voices.data[0]?.name);
```

Por debajo llama al mismo `GET /v1/catalogs/items`.

## Usar una voz en un agente

El `id` del ítem de catálogo es lo que se envía al crear o actualizar la versión
del agente. La lista completa de campos está en la referencia de
[Agent Versions](/api-reference/introduction).