> ## 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. # Crear ítem de catálogo > Registra un nuevo ítem en el catálogo seleccionado. Para `scope=workspace` debe enviarse el header `x-workspace-id`. Requiere el scope `catalogs:write`. ## OpenAPI ````yaml /openapi/public-api.yaml post /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 Bearer y respetan los contratos documentados en `docs/modules`. 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: [] 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: Agent Knowledge description: Uploads y sincronización de knowledge bases asociadas al agente. - name: Agent Tags description: Gestión de etiquetas asociadas a 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: Knowledge description: Gestión de recursos de conocimiento asociados a tools. - 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: Voices description: Catálogo consolidado de voces provenientes de proveedores externos. - name: Catalogs description: > Gestión centralizada de catálogos (idiomas, tonos, voces, etiquetas) con alcance global o específico por workspace. Scopes requeridos: `catalogs:read` para consultas y `catalogs:write` para creación y modificaciones. - 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: Agent Stages description: > Autoría de stages del blueprint del agente, abarcando orden, prompts y validaciones previas a la publicación. Scopes requeridos: `stages:read` para consultas y `stages:write` para creación y edición. La validación se ejecuta automáticamente en cada mutación y la sincronización con proveedores 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:*` (o políticas equivalentes bajo `stages:*`). - 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. paths: /v1/catalogs/items: post: tags: - Catalogs summary: Crear ítem de catálogo description: > Registra un nuevo ítem en el catálogo seleccionado. Para `scope=workspace` debe enviarse el header `x-workspace-id`. Requiere el scope `catalogs:write`. operationId: createCatalogItem parameters: - $ref: '#/components/parameters/XWorkspaceId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CatalogItemCreateRequest' examples: createVoice: summary: Registrar voz específica para un workspace value: type: voice scope: workspace workspaceId: a44bb95e-9f01-4d19-8b62-1f6f2b8e8363 name: Valentina MX description: Voz femenina cálida para campañas LATAM metadata: language: es-MX gender: female tone: warm responses: '201': description: Ítem creado correctamente. content: application/json: schema: $ref: '#/components/schemas/CatalogItemDetail' '400': description: Validaciones de negocio fallidas o metadata inconsistente. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Conflicto por identificadores duplicados dentro del catálogo. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: parameters: XWorkspaceId: name: x-workspace-id in: header required: true description: Identificador del workspace multi-tenant. schema: type: string format: uuid schemas: CatalogItemCreateRequest: type: object description: Payload para registrar un nuevo ítem en el catálogo. required: - type - scope - name - description - metadata properties: type: type: string enum: - language - message_style - tone_style - tag - voice scope: type: string enum: - global - workspace description: >- Determina si el ítem es global o específico del workspace que realiza la llamada. workspaceId: type: string format: uuid description: >- Workspace objetivo cuando `scope` es `workspace`. Se omite para ítems globales. name: type: string minLength: 1 maxLength: 120 description: type: string minLength: 1 maxLength: 500 systemIdentifier: type: string minLength: 1 maxLength: 120 pattern: ^[a-z0-9]+(?:[-_][a-z0-9]+)*$ description: >- Identificador técnico único dentro del catálogo. Si se omite se genera desde el nombre. metadata: type: object description: Metadata específica dependiente del tipo de catálogo. isActive: type: boolean default: true 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' - if: properties: scope: const: workspace then: properties: workspaceId: type: string format: uuid description: Workspace objetivo cuando `scope` es `workspace`. required: - workspaceId CatalogItemDetail: allOf: - $ref: '#/components/schemas/CatalogItemSummary' ErrorResponse: type: object properties: code: type: string description: Código principal del error (alto nivel). message: type: string description: Mensaje legible para humanos. details: type: object description: > Información adicional específica del error. 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: - code - message 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 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' 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 ````