> ## 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. # Listar ítems de catálogo > Retorna el catálogo consolidado (global + workspace) respetando filtros por tipo y workspace. Soporta paginación, orden por nombre y filtros avanzados basados en la convención del API Query Builder (`docs/api-query-builder.md`). Requiere el scope `catalogs:read`. **No hay sparse fieldsets ni expansión de relaciones**: `fields` e `include` se aceptan sin error pero el servidor los descarta, así que la respuesta siempre viene completa. ## OpenAPI ````yaml /openapi/public-api.yaml get /v1/catalogs/items openapi: 3.1.0 info: title: Agents Studio API version: 1.0.0 description: > API del backend de Agents Studio. Expone servicios multi-tenant para gestionar agentes (texto y voz), catálogo de herramientas, habilitación de workspaces y operaciones de telefonía. Todos los endpoints requieren autenticación y respetan los contratos documentados en `docs/modules`. Hay dos formas de autenticar, equivalentes en cobertura: `Authorization: Bearer ` para la sesión de un usuario, o el header `x-api-key` con una API key del workspace. La llave vale en cualquier ruta no pública y lleva el workspace dentro, así que con `x-api-key` no hace falta mandar `x-workspace-id`. license: name: Proprietary url: https://getsupervisor.ai/legal/terms servers: - url: https://api-prod.studio.getsupervisor.ai description: Producción - url: https://sandbox.agents.studio.getsupervisor.ai description: Sandbox security: - BearerAuth: [] - ApiKeyAuth: [] tags: - name: Agents description: > Gestión general de agentes y sus metadatos. Scopes requeridos: `agents:read` para consultas y `agents:write` para creación, actualización y operaciones sobre teléfonos. - name: Agent Versions description: Versionado y mantenimiento de versiones publicadas de los agentes. - name: Agent Schedules description: >- Configuración de horarios regulares y excepciones puntuales para controlar la disponibilidad de los agentes. - name: Campaigns description: > Gestión de campañas masivas basadas en CSV para ejecutar agentes de forma batch. Scopes requeridos: `campaigns:read` para consultas y `campaigns:write` para creación. - name: Calls description: | Consultas de llamadas (Speech Analytics) disponibles para el workspace. Scopes requeridos: `calls:read`. - name: Agent Instructions description: > Operaciones sobre instrucciones (prompt) gestionadas por los usuarios finales para guiar y corregir el comportamiento del agente. Las instrucciones se aplican a la versión activa del agente, se mantienen como texto libre sin formato (1 a 500 caracteres) y su prioridad se controla mediante el campo `order`. Scopes requeridos: `agent-instructions:read` para consultas y `agent-instructions:write` para creación o edición. - name: Catalogs description: > Gestión centralizada de catálogos (idiomas, estilos de mensaje, tonos, etiquetas, voces y eventos de webhook) con alcance global o específico por workspace. Las voces del workspace se consultan aquí, con `GET /v1/catalogs/items?type=voice`. Scopes requeridos: `catalogs:read` para consultas y `catalogs:write` para creación y modificaciones. - name: Catalog Templates description: > Catálogo de plantillas de agente publicadas. Sirve para descubrir qué plantillas hay disponibles y con qué `agentVersionId` clonarlas mediante `POST /v1/agents/from-template`. Scopes requeridos: `catalogs:read`. - name: Agent Phones description: Conexión y desconexión de teléfonos asignados a agentes. - name: API Keys description: Gestión de credenciales de acceso programático y sus permisos. - name: Agent Blueprints description: > Gestión del blueprint (personalidad) asociado a cada versión de agente. Scopes requeridos: `agent-blueprints:read` para lectura y `agent-blueprints:write` para cambios en blueprint. - name: Blueprint Stages description: > Autoría de stages de un blueprint del agente, abarcando orden, prompts y validaciones previas a la publicación. Todas las rutas cuelgan del blueprint (`/v1/agents/{agentId}/blueprints/{blueprintId}/stages`), así que hay que resolver primero el `blueprintId` con `GET /v1/agents/{agentId}/blueprints`. Scopes requeridos: `blueprint-stages:read` para consultas y `blueprint-stages:write` para creación y edición. La validación del grafo se ejecuta automáticamente en cada mutación y la sincronización con el proveedor sucede mediante jobs internos tras los cambios. - name: Stage Triggers description: > Gestión detallada de triggers que conectan stages dentro del blueprint y definen las transiciones conversacionales. Scopes requeridos: `stage-triggers:read` y `stage-triggers:write`. - name: Workspaces description: Gestión multi-tenant y habilitación de credenciales por workspace. - name: Tools description: > Catálogo y ejecución de tools disponibles para los agentes. Scopes requeridos: `tools:read` para listar y `tools:execute` para ejecutar tools. - name: Webhooks description: > Gestión de webhooks por workspace para suscribirse a eventos del dominio y recibir notificaciones HTTP. Scopes requeridos: `webhooks:read` para consultas y `webhooks:write` para crear, actualizar o eliminar webhooks y suscripciones. - name: SIP Trunks description: > Provisionamiento y gestión de SIP trunks para conectar agentes de voz con carriers PSTN (Twilio, ccc2.uno, etc.) via Kamailio. Genera credenciales digest automaticamente. Scopes requeridos: `sip:read` para consultas y `sip:write` para creación, actualización y eliminación. **Estas cinco rutas sólo existen si el despliegue tiene configurada la base del gateway SIP** (`SIP_DB_HOST` y `SIP_DB_PASSWORD`). Cuando faltan, el módulo arranca deshabilitado y su controller ni se registra: las cinco rutas responden **404 de ruta inexistente**, que desde fuera es indistinguible del 404 de «trunk no encontrado» que documentan las operaciones por ID. Los sandboxes de rama arrancan así, de modo que un 404 sobre `GET /v1/sip/trunks` —el listado, que nunca depende de un ID— es la forma de distinguir «el entorno no tiene gateway SIP» de «ese trunk no existe»: si el listado también da 404, la superficie no está montada y crear el trunk de nuevo no arregla nada. - name: Documents description: > Gestión de documentos asociados al workspace. Permite obtener URLs presignadas para subir archivos que luego se referencian al crear o personalizar agentes. Scopes requeridos: `documents:write`. - name: Message Templates description: > Gestión de message templates de WhatsApp (Kapso). Permite crear, listar y eliminar templates, así como consultar el estado de la conexión con el número de teléfono configurado. Scopes requeridos: `agents:read` para consultas y `agents:write` para creación y eliminación. - name: Billing description: | Consulta del balance de consumo del workspace sobre el plan contratado. Scopes requeridos: `billing:read`. - name: Usage description: | Consultas de consumo de recursos agregado por agente. Scopes requeridos: `usage:read`. - name: Uploads description: > Subida de archivos por URL prefirmada: la API reserva el sitio y devuelve la URL, y el cliente sube contra el almacén sin que los bytes pasen por aquí. Toda escritura exige `uploads:write`, y la firma exige **además** el scope que decide el namespace de la ruta: `agent-briefs` y `avatars` exigen `agents:write`, y `knowledge-sources` exige `knowledge-bases:write`. Cada namespace declara además qué acepta. `avatars` sólo admite PNG, JPEG y WEBP —y **no** SVG: se sirven en línea, y un SVG es texto ejecutable—, con un archivo por lote y 1 MiB como máximo. - name: Health description: > Sonda de disponibilidad del servicio. No requiere autenticación ni `X-Workspace-Id`. - name: Knowledge Bases description: > Bases de conocimiento del workspace: el material que el agente consulta durante la conversación. El prefijo nombra el recurso y no la tool que lo implementa, así que renombrar la tool `knowledge` no mueve estas rutas. Las sirve un plugin instalable, y eso tiene una consecuencia visible: si la tool no está abierta para el workspace, **todas** responden `404` —no `403`—. Una feature que no está disponible para un cliente no existe para él. Scopes requeridos: `knowledge-bases:read` para consultas y `knowledge-bases:write` para el alta, la baja y el mantenimiento de sus documentos. paths: /v1/catalogs/items: get: tags: - Catalogs summary: Listar ítems de catálogo description: > Retorna el catálogo consolidado (global + workspace) respetando filtros por tipo y workspace. Soporta paginación, orden por nombre y filtros avanzados basados en la convención del API Query Builder (`docs/api-query-builder.md`). Requiere el scope `catalogs:read`. **No hay sparse fieldsets ni expansión de relaciones**: `fields` e `include` se aceptan sin error pero el servidor los descarta, así que la respuesta siempre viene completa. operationId: listCatalogItems parameters: - $ref: '#/components/parameters/XWorkspaceId' - $ref: '#/components/parameters/PageParam' - $ref: '#/components/parameters/LimitParam' - $ref: '#/components/parameters/SortParam' - $ref: '#/components/parameters/SearchParam' - $ref: '#/components/parameters/FilterParam' responses: '200': description: Catálogo paginado de ítems disponibles para el workspace. content: application/json: schema: $ref: '#/components/schemas/CatalogItemListResponse' examples: voices: summary: Voces activas del workspace value: data: - id: 7f8d9e4e-9795-4f76-9a1d-1e8b3f8e7c42 type: voice systemIdentifier: es_mx_lite scope: workspace workspaceId: a44bb95e-9f01-4d19-8b62-1f6f2b8e8363 name: Valentina MX description: Voz femenina cálida para campañas LATAM isActive: true metadata: language: es-MX gender: female tone: warm previewUrl: >- https://cdn.getsupervisor.ai/previews/valentina-mx.mp3 createdAt: '2025-10-10T10:22:11.000Z' updatedAt: '2025-10-18T08:44:09.000Z' links: self: >- https://api.agents.studio.getsupervisor.ai/v1/catalogs/items/7f8d9e4e-9795-4f76-9a1d-1e8b3f8e7c42 catalog: >- https://api.agents.studio.getsupervisor.ai/v1/catalogs/items?filter=eq(type,%22voice%22) meta: total: 12 page: 1 limit: 20 hasNext: false hasPrevious: false sort: - name appliedFilters: type: voice '400': description: Parámetros de consulta inválidos o filtros no permitidos. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: parameters: XWorkspaceId: name: x-workspace-id in: header required: false description: >- Identificador del workspace multi-tenant. **Obligatorio al autenticar con `Authorization: Bearer`**, donde su ausencia devuelve `400 Workspace context is required`. Con `x-api-key` es opcional: la llave ya identifica a su workspace y lo que mandes aquí se ignora. schema: type: string format: uuid PageParam: name: page in: query required: false description: Número de página (>= 1). Por defecto es 1. schema: type: integer minimum: 1 default: 1 LimitParam: name: limit in: query required: false description: Tamaño de página (1..100). Por defecto 20. schema: type: integer minimum: 1 maximum: 100 default: 20 SortParam: name: sort in: query required: false description: >- Lista separada por comas de campos a ordenar. Usa prefijo '-' para orden descendente. schema: type: string example: createdAt,-id SearchParam: name: q in: query required: false description: Búsqueda de texto global sobre campos soportados del recurso. schema: type: string example: soporte FilterParam: name: filter in: query required: false description: > Expresión de filtros combinados generada con el API Query Builder. Utiliza funciones como `and(...)`, `or(...)`, `eq(...)`, `like(...)`, etc. Consulta `docs/api-query-builder.md` para la gramática completa y ejemplos adicionales. schema: $ref: '#/components/schemas/QueryFilters' examples: estadoActivoConNombre: summary: Filtrar agentes activos cuyo nombre contiene "ventas" value: and(eq(status,"active"),like(name,"%ventas%")) schemas: CatalogItemListResponse: type: object required: - data - meta properties: data: type: array items: $ref: '#/components/schemas/CatalogItemSummary' meta: $ref: '#/components/schemas/PaginationMeta' ErrorResponse: type: object description: > Forma común de los errores de la API. El filtro global responde `{ statusCode, error, message, path, timestamp }`; los 400 que produce la validación del body llegan con `message` como arreglo de strings (uno por regla incumplida) y sin `path` ni `timestamp`. `code` y `details` **no** son parte del contrato general: sólo los traen los rechazos que los construyen explícitamente (por ejemplo `UPLOAD_REJECTED_BY_NAMESPACE` al reutilizar un archivo en otro namespace, o `PROVIDER_CAPACITY_EXHAUSTED` en un 429). No ramifiques por `code` en el resto de las rutas: ahí no viene. properties: statusCode: type: integer description: Código HTTP de la respuesta. error: type: string description: Etiqueta HTTP del estado (`Bad Request`, `Not Found`, …). message: oneOf: - type: string - type: array items: type: string description: >- Mensaje legible para humanos. Es un arreglo cuando el 400 viene de la validación del body. path: type: string description: >- Ruta de la petición que falló. Presente en los errores que emite el filtro global. timestamp: type: string format: date-time description: >- Momento en que se generó la respuesta de error. Presente en los errores que emite el filtro global. code: type: string description: >- Identificador estable del rechazo. Sólo en los errores que lo declaran; ausente en el resto. details: type: object description: > Información adicional específica del error, presente sólo cuando el rechazo la construye. Cuando aplique, `details.subcode` provee un identificador estable para que el frontend decida qué UI mostrar. properties: subcode: type: string description: >- Identificador específico del error (p.ej. `WORKSPACE_NOT_PROVISIONED`). workspaceId: type: string format: uuid description: Identificador de workspace relacionado cuando aplica. additionalProperties: true required: - statusCode - message QueryFilters: type: string description: > Expresión string compatible con el API Query Builder. Soporta composición de funciones (`and`, `or`) y operadores (`eq`, `like`, `between`, etc.) para filtrar resultados. example: and(eq(status,"active"),like(name,"%ventas%")) CatalogItemSummary: type: object description: Representación de un ítem de catálogo disponible para los agentes. properties: id: type: string format: uuid type: type: string enum: - language - message_style - tone_style - tag - voice - webhook_event description: Tipo lógico de catálogo al que pertenece el ítem. systemIdentifier: type: string description: >- Identificador técnico único dentro del catálogo (snake-case o kebab-case). scope: type: string enum: - global - workspace description: Determina si el ítem aplica globalmente o a un workspace específico. workspaceId: type: - string - 'null' format: uuid description: Workspace propietario cuando `scope` es `workspace`. name: type: string description: type: string isActive: type: boolean metadata: type: object description: Metadata específica dependiente del tipo de catálogo. createdAt: type: string format: date-time updatedAt: type: string format: date-time links: $ref: '#/components/schemas/CatalogItemLinks' required: - id - type - systemIdentifier - scope - name - description - isActive - metadata - createdAt - updatedAt - links allOf: - if: properties: type: const: language then: properties: metadata: $ref: '#/components/schemas/CatalogItemLanguageMetadata' - if: properties: type: const: message_style then: properties: metadata: $ref: '#/components/schemas/CatalogItemMessageStyleMetadata' - if: properties: type: const: tone_style then: properties: metadata: $ref: '#/components/schemas/CatalogItemToneStyleMetadata' - if: properties: type: const: tag then: properties: metadata: $ref: '#/components/schemas/CatalogItemTagMetadata' - if: properties: type: const: voice then: properties: metadata: $ref: '#/components/schemas/CatalogItemVoiceMetadata' PaginationMeta: type: object properties: total: type: integer page: type: integer limit: type: integer hasNext: type: boolean hasPrevious: type: boolean description: Indica si existe una página previa a la actual. required: - total - page - limit - hasNext - hasPrevious CatalogItemLinks: type: object description: Enlaces HATEOAS mínimos para la navegación entre catálogos. properties: self: type: string format: uri description: URL absoluta del ítem de catálogo. catalog: type: string format: uri description: URL del catálogo raíz al que pertenece el ítem. required: - self - catalog securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT ApiKeyAuth: type: apiKey in: header name: x-api-key description: > API key para autenticacion programatica por workspace. El workspace viaja dentro de la propia llave, así que con `x-api-key` no hace falta el header `x-workspace-id`. La llave sólo autentica en el despliegue cuyo entorno coincide con el `environment` con el que se emitió: si no coinciden, cualquier ruta responde `401 API key environment mismatch` antes de mirar los scopes. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.