API REST de AI Studio

AI Studio ofrece su funcionalidad a través de la API del panel, la que usa la propia interfaz de UTILIA OS, que se llama con la sesión de un usuario. No forma parte del SDK público ni de la API externa (/api/external/v1): si desarrollas fuera de UTILIA OS, usa la herramienta MCP ai_studio (ver Siguiente paso).

Dirección base, autenticación y plan

Todos los endpoints cuelgan de /api/ai-studio y exigen la cabecera Authorization: Bearer <JWT> de una sesión iniciada. El plan de tu organización tiene que incluir el aplicativo AI Studio; si no, la respuesta es 403 MODULE_NOT_ENABLED. Sin sesión o con la sesión caducada, la respuesta es 401; sin el permiso o sin acceso al activo concreto, 403.

Permisos

Cada operación comprueba un permiso de AI Studio y, si actúa sobre un activo concreto, también que el usuario tenga acceso a ese activo (lectura, edición o administración).

AI_STUDIO_VIEWpermiso

Listar y ver activos, registrar uso y reacciones, abrir el canal SSE.

AI_STUDIO_CREATEpermiso

Crear y duplicar activos.

AI_STUDIO_EDITpermiso

Modificar activos y crear versiones.

AI_STUDIO_DELETEpermiso

Eliminar activos.

AI_STUDIO_PUBLISHpermiso

Publicar la versión activa de un activo.

AI_STUDIO_VERIFYpermiso

Marcar un activo como verificado. Por defecto, solo el Super Administrador.

AI_STUDIO_SHAREpermiso

Compartir un activo con personas o grupos concretos.

Resumen de endpoints

Endpoints del catálogo

POST /ai-studio/assets

Cabeceras

Authorizationstringobligatorio

Bearer <JWT>

Content-Typestringobligatorio

application/json

Cuerpo de la petición

Ejemplo de petición

curl -X POST "https://os.utilia.ai/api/ai-studio/assets" \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "PROMPT",
    "name": "Redactor de respuesta comercial",
    "description": "Redacta una respuesta comercial empática para una oportunidad del CRM a partir de su contexto.",
    "bodyMarkdown": "Eres un responsable comercial experto.\n\nEl cliente es {{cliente}}...",
    "iconName": "sparkles",
    "visibility": "DEPARTMENT",
    "departments": ["cl8ab9cd0000exampledept01"],
    "tags": ["crm", "ventas", "castellano"]
  }'

Respuesta correcta (201)

{
  "id": "cl9z1z0000exampleasset01",
  "type": "PROMPT",
  "slug": "redactor-de-respuesta-comercial",
  "name": "Redactor de respuesta comercial",
  "status": "DRAFT",
  "visibility": "DEPARTMENT",
  "currentVersionId": "cl9z1z0000exampleversion01",
  "currentVersion": {
    "version": "1.0.0",
    "publishedAt": null
  },
  "createdAt": "2026-06-13T08:00:00.000Z"
}

GET /ai-studio/assets

Parámetros de consulta

GET /ai-studio/assets/by-slug/:slug

Si el slug es el actual, devuelve el detalle del activo. Si es uno antiguo, responde 301 con la cabecera Location apuntando al actual, para que los enlaces viejos sigan funcionando. Si no hay coincidencia, responde 404.

Métricas de uso y reacciones

Estos tres endpoints mantienen los contadores del activo (usageCount, thumbsUp, thumbsDown) y guardan un registro por usuario. Solo exigen AI_STUDIO_VIEW y acceso de lectura al activo. Después emiten un evento que el canal SSE envía al resto de personas de tu organización.

POST /ai-studio/assets/:id/use

Cuerpo de la petición (opcional)

entityTypestring

Tipo de entidad del ecosistema desde la que se usó el activo (por ejemplo, una oportunidad o un ticket).

entityIdstring

Identificador de esa entidad. Permite atribuir el uso a su contexto de origen.

Ejemplo de petición

curl -X POST "https://os.utilia.ai/api/ai-studio/assets/cl9z1z0000exampleasset01/use" \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{ "entityType": "OPPORTUNITY", "entityId": "cl9opp0000exampleopp01" }'

Respuesta correcta (201)

{
  "id": "cl9z1z0000exampleasset01",
  "usageCount": 42
}

POST /ai-studio/assets/:id/thumbs-up

Cada usuario cuenta una sola vez. Si ya había votado a favor, el contador no sube. Si tenía una reacción negativa, se retira (baja thumbsDown) y se registra la positiva. No lleva cuerpo.

Ejemplo de petición

curl -X POST "https://os.utilia.ai/api/ai-studio/assets/cl9z1z0000exampleasset01/thumbs-up" \
  -H "Authorization: Bearer <JWT>"

Respuesta exitosa (201)

{
  "id": "cl9z1z0000exampleasset01",
  "thumbsUp": 18,
  "thumbsDown": 1
}

POST /ai-studio/assets/:id/thumbs-down

Funciona igual que thumbs-up, al revés. Si el usuario tenía una reacción positiva, se retira (baja thumbsUp) y se registra la negativa. Si ya había votado en contra, el contador no cambia. No lleva cuerpo.

Respuesta exitosa (201)

{
  "id": "cl9z1z0000exampleasset01",
  "thumbsUp": 17,
  "thumbsDown": 2
}

Cambios del catálogo en tiempo real

GET /ai-studio/events

Con este endpoint la galería de AI Studio se actualiza sola cuando otra persona de tu organización cambia el catálogo. Exige AI_STUDIO_VIEW, que se comprueba al abrir la conexión.

Como EventSource no permite cabeceras propias, el canal se autentica con un token SSE de corta duración en el parámetro token: GET /api/ai-studio/events?token=<sseJwt>. Pide antes ese token con POST /api/auth/sse-token, usando tu JWT de sesión. El token de sesión normal no se acepta en la dirección.

Características

Aislamiento por organizacióncomportamiento

Solo llegan eventos de la organización del usuario. No hay excepción por rol: un Super Administrador tampoco recibe el catálogo de otras organizaciones.

Señal de vida20 s

Evento heartbeat periódico para mantener viva la conexión a través de proxies.

Conexiones simultáneasmáximo 5 por usuario

Al superarlo, el endpoint responde 429.

Eventos emitidos

Cada evento del catálogo incluye al menos assetId, organizationId y un campo type con el nombre interno del evento (por ejemplo, ai-asset.published).

Ejemplo de consumo en JavaScript

// 1. Obtener el token SSE efímero con el JWT de sesión.
const tokenResponse = await fetch('https://os.utilia.ai/api/auth/sse-token', {
  method: 'POST',
  headers: { Authorization: `Bearer ${jwt}` },
});
const { token } = await tokenResponse.json();
 
// 2. Abrir el stream con ese token como query param.
const source = new EventSource(
  `https://os.utilia.ai/api/ai-studio/events?token=${token}`,
);
 
source.addEventListener('connected', (event) => {
  console.log('Conectado:', JSON.parse(event.data));
});
 
source.addEventListener('asset-published', (event) => {
  const payload = JSON.parse(event.data);
  console.log('Activo publicado:', payload.assetId);
});
 
source.onerror = () => {
  // El navegador reintenta la conexión automáticamente.
  console.warn('Conexión SSE interrumpida; reintentando...');
};

Versiones y adjuntos

Las versiones cuelgan del activo. Crear una versión o restaurar una anterior queda en el historial, y cada versión puede tener archivos adjuntos.

Importar y exportar

POST /ai-studio/assets/import

Content-Type multipart/form-data con el campo file.

curl -X POST "https://os.utilia.ai/api/ai-studio/assets/import" \
  -H "Authorization: Bearer <JWT>" \
  -F "file=@mi-skill.zip"

Devuelve el activo creado, con la primera versión ya rellena y los adjuntos subidos.

GET /ai-studio/assets/:id/export

• Cabecera Content-Type: application/zip.
• Cabecera Content-Disposition: attachment; filename="<slug>.zip".
• Cuerpo: el archivo.

Marketplace

El marketplace es un catálogo de activos de IA compartido entre las organizaciones de UTILIA OS: tu equipo puede enviar a él sus propios activos publicados e instalar copias de los que han compartido otras empresas. Lo que se envía no aparece en el catálogo hasta que el equipo de UTILIA OS lo revisa y lo aprueba. En la interfaz está en la pestaña Marketplace, necesitas entrar con tu cuenta de AI Studio.

Requisitos

Además del aplicativo AI Studio en el plan, la organización tiene que tener activada la función Marketplace del AI Studio, en Ajustes › Organización, necesitas entrar con tu cuenta › Funciones opcionales. Si está desactivada, todos los endpoints del marketplace responden 403.

AI_STUDIO_MARKETPLACE_VIEWpermiso

Ver el catálogo, las reseñas y tus instalaciones, denunciar una entrada, marcar reseñas como útiles y abrir el canal SSE.

AI_STUDIO_MARKETPLACE_INSTALLpermiso

Instalar una entrada en tu biblioteca.

AI_STUDIO_MARKETPLACE_SUBMITpermiso

Enviar activos propios al marketplace, y cambiar o retirar tus entradas.

AI_STUDIO_MARKETPLACE_REVIEWpermiso

Crear, modificar y borrar tus reseñas.

Enviar un activo

assetIdstringobligatorio

Identificador del activo. Tiene que ser tuyo y estar en estado PUBLISHED.

categoryenumobligatorio

PRODUCTIVITY, SALES_CRM, DEVELOPMENT, FINANCE, MARKETING, CUSTOMER_SUPPORT, ANALYTICS, AUTOMATION, DOCUMENTATION, COMMUNICATION u OTHER.

tagsstring[]

Hasta 15 etiquetas de 48 caracteres como máximo.

pricingenum

Solo se admite FREE, que es el valor por defecto. PREMIUM responde 400.

acceptPolicybooleanobligatorio

Aceptación de la política de publicación. Tiene que ser true.

Mientras no está archivada, puedes cambiar su categoría o sus etiquetas, y retirarla cuando quieras:

Consultar el catálogo

categoryenum

Una de las categorías del envío.

pricingenum

FREE o PREMIUM.

sortenum

RECENT (por defecto), POPULAR, TOP_RATED, FEATURED o MOST_DOWNLOADED.

featuredboolean

true para ver solo las entradas destacadas vigentes.

searchstring

Busca en el nombre, la descripción y las etiquetas, sin distinguir mayúsculas.

limitnumber

De 1 a 100. Por defecto, 20.

offsetnumber

Desplazamiento. Por defecto, 0.

Instalar una entrada

Instalar crea en tu biblioteca una copia privada del activo, con su versión activa y sus adjuntos. La copia es tuya: si el autor publica después una versión nueva, tu copia no se modifica sola.

La respuesta incluye installId, installedAssetId (el activo nuevo de tu biblioteca), installedVersion, y filesCopied y filesFailed con el resultado de la copia de adjuntos. No se puede instalar una entrada que no esté aprobada ni un activo del que eres autor: en esos casos la respuesta es 400.

Reseñas

Solo se puede reseñar una entrada aprobada que hayas instalado y que no sea tuya. Cada persona tiene una reseña por entrada: enviar otra la sustituye.

Las reseñas de personas de otras empresas se muestran anónimas: llegan con user.name igual a «Usuario de otra empresa» y sin userId ni organizationId.

Cambios del marketplace en tiempo real

Cada persona recibe solo lo que le afecta:

• Todos: marketplace-featured, marketplace-unfeatured, marketplace-reviewed, marketplace-review-updated, marketplace-review-deleted y marketplace-review-helpful, para refrescar el catálogo y las valoraciones.
• Quien envió la entrada: marketplace-under-review, marketplace-approved, marketplace-rejected, marketplace-archived y marketplace-new-version-pending-review (has publicado una versión nueva del activo y hay que volver a enviarla a revisión).
• Quien envió la entrada y quien la instala: marketplace-installed.

Códigos de error

Siguiente paso

Para usar AI Studio desde asistentes de IA o clientes MCP, utiliza la herramienta MCP ai_studio: lo explica Herramientas MCP de AI Studio. Cómo se usa AI Studio dentro del producto está en AI Studio.

• Herramientas MCP de AI StudioAccede al catálogo desde asistentes de IA y clientes MCP.
• Analítica de IAUso, coste y aceptación de la IA de tu aplicación.