La API de la consola
La API que usa la consola de desarrolladores: cómo se autentica una clave de API de la cuenta, qué hace a propósito y qué no, y las rutas principales de aplicaciones, fichas, empresas de prueba e instalaciones.
Actualizado el . 5 min de lectura
Todo lo que ves en la consola lo sirve la misma API. Sus rutas propias empiezan por https://os.utilia.ai/api/developer/v1 y solo responden a una cuenta de desarrollador: con una cuenta de empresa, 403 DEVELOPER_ACCOUNT_REQUIRED. Tus aplicaciones se consultan en las rutas de Integraciones, https://os.utilia.ai/api/integrations/apps, las mismas que usa una empresa con las suyas.
Hay tres formas de llamarla, y cada una sirve para algo:
Quién llama a la API de la consola
Clave de API de la cuenta
Tu integración continua
utk_ creada en Cuenta › Claves de API. Para scripts y pipelines: consultar, preparar fichas y gestionar empresas de prueba.Servidor MCP con OAuth
Tu asistente de IA
Tu sesión
Tú en la consola
Esta página es la de la clave. Para crearla, mira Claves de API de la cuenta; para el asistente, Conectar tu asistente de IA a la consola.
Autenticarse con una clave
Envía la clave en la cabecera Authorization, con Bearer delante, en cada petición y desde un servidor. No vale en la dirección ni en X-Api-Key, y UTILIA OS rechaza las peticiones con clave que salen de un navegador.
Authorization: Bearer utk_…Antes de nada, comprueba la clave. Estas dos rutas solo responden a una clave y no tocan ningún dato:
/api/v2/organization-api-keys/currentQuién es la clave: persona responsable, permisos efectivos en developer-apps y developer-sandboxes, caducidad y cupo que le queda esta hora.
/api/v2/organization-api-keys/current/diagnosticsSi funciona y qué le falta: veredicto, permisos por módulo, llamadas rechazadas en 24 horas y hallazgos con quién los arregla. En una cuenta de desarrollador, organization.kind vale developer.
curl 'https://os.utilia.ai/api/developer/v1/listings' \
-H "Authorization: Bearer $UTILIA_API_KEY"Cada petición cuenta en el cupo por hora de la clave y se comprueba de nuevo: si revocas la clave o cambias el rol de su persona responsable, la petición siguiente ya lo nota.
Lo que hace a propósito y lo que no
Con una clave, la API de la consola hace lo que una integración continua necesita y nada que deje credenciales vivas, comprometa a la cuenta o mueva dinero.
- Sí: consultar tus aplicaciones y todo lo que cuentan de sí mismas; preparar fichas, sus imágenes y la conversación con la revisión; crear, restablecer y borrar empresas de prueba, leer sus correos y simular suscripciones en ellas.
- No, a propósito: crear, cambiar o borrar aplicaciones y renovar sus claves, porque fabricaría credenciales que sobreviven a la clave; enviar una ficha a revisión, que acepta las Normas del catálogo; poner precios y planes; instalar para probar y abrir una empresa de prueba, que son de una persona en su sesión; y el equipo, los datos fiscales, la vinculación con tu empresa y la confirmación de operaciones críticas.
- El dinero, solo con la sesión de una persona: ingresos, extractos, ventas de cada aplicación, cuenta de cobro y dejar de vender no admiten clave ni asistente de IA.
Aplicaciones
Tus aplicaciones son las de Integraciones. Con developer-apps:read se consultan; crearlas y cambiarlas lo hace una persona en la consola o tu asistente de IA.
/api/integrations/appsTus aplicaciones, con su estado.
/api/integrations/apps/:idUna aplicación: sus permisos, sus avisos, su inicio de sesión y su clave, sin secretos.
/api/integrations/apps/:id/metricsPeticiones, latencia, errores, rutas más usadas y avisos enviados (también por partes: /metrics/requests, /latency, /errors, /endpoints y /webhooks).
/api/integrations/apps/:id/webhook-deliveriesLos avisos enviados a tu servidor, con su respuesta; /:deliveryId, el detalle de uno.
/api/integrations/apps/:id/diagnosisLa comprobación de la conexión de la aplicación (en la consola, Registros › Llamadas a la API), con /calls y /brief. Su flujo en tiempo real no admite clave.
/api/integrations/apps/:appId/errorsLos errores de la aplicación agrupados, con /stats, /events, /:hash y la exportación /export.csv.
Fichas
La ficha es lo que ven las empresas en el catálogo. Leer va con developer-apps:read; preparar, con developer-apps:write.
/api/developer/v1/optionsLo que puede llevar una ficha: permisos, avisos, categorías, modelos de precio, ubicación de los datos y límites de textos e imágenes.
/api/developer/v1/listingsLas fichas de la cuenta, con su estado y sus instalaciones.
/api/developer/v1/listingsCrea la ficha y su primer borrador para una de tus aplicaciones. Si ya la tiene, devuelve la que hay.
/api/developer/v1/listings/:idLa ficha, su borrador, el historial de versiones y decisiones, y sus imágenes.
/api/developer/v1/listings/:id/draftGuarda el borrador; admite guardados parciales.
/api/developer/v1/listings/:id/checksLa lista «Antes de enviar», control a control.
/api/developer/v1/listings/:id/mediaSube el icono o una captura; DELETE /media/:mediaId la quita y GET /media/:mediaId la enseña.
/api/developer/v1/listings/:listingId/revisions/:revisionId/messagesResponde a la revisión o recurre su decisión; el GET de la misma ruta trae el hilo.
/api/developer/v1/listings/:id/plansLos planes y el precio de la ficha, solo para leer: cambiarlos lo hace una persona o tu asistente de IA.
También con developer-apps:write: POST /listings/:id/withdraw-submission cancela un envío, POST /listings/:id/unpublish retira la ficha del catálogo y POST /listings/:id/republish vuelve a publicar la última versión aprobada.
POST /listings/:id/submit, el envío a revisión, responde 403 APP_CATALOG_HUMAN_SESSION_REQUIRED con una clave: lo hace una persona desde la consola, porque acepta las Normas del catálogo.
La cuenta
Con developer-apps:read se consulta el resumen de la cuenta y el perfil público; cambiar el perfil pide developer-apps:write.
/api/developer/v1/accountResumen de la cuenta: perfil, si los datos fiscales están completos, dominio, condiciones, empresas de prueba y vinculación. Con una clave nunca lleva los saldos de Ingresos.
/api/developer/v1/profileEl perfil público: nombre, web, correo de soporte, dominio y su verificación. PUT lo cambia.
Aceptar las Condiciones para desarrolladores y las condiciones de venta lo hace la persona titular desde la consola: con una clave, 403 APP_CATALOG_HUMAN_SESSION_REQUIRED.
Empresas de prueba
Con developer-sandboxes:write. Una empresa recién creada se prepara en segundo plano: pide su ficha hasta que su estado sea READY.
/api/developer/v1/sandboxesLas empresas de prueba de la cuenta. También responde con developer-apps:read.
/api/developer/v1/sandboxesCrea una empresa de prueba con datos de demostración.
/api/developer/v1/sandboxes/:idSu ficha: estado, datos de demostración, caducidad e instalaciones de prueba.
/api/developer/v1/sandboxes/:idLe cambia el nombre.
/api/developer/v1/sandboxes/:id/resetRestablece los datos de demostración.
/api/developer/v1/sandboxes/:id/deleteLa borra con todos sus datos. No se puede deshacer: lleva su nombre exacto en confirmName.
/api/developer/v1/sandboxes/:id/emailsLos correos que ha capturado; /:emailId, uno entero.
POST /sandboxes/:id/open, abrir la empresa de prueba, responde 403 SANDBOX_HUMAN_SESSION_REQUIRED con una clave: entra una persona.
Instalaciones
/api/developer/v1/listings/:id/installationsLas empresas que tienen instalada la ficha, con developer-apps:read.
/api/developer/v1/sandboxes/:id/installations/:installationId/subscriptionLa suscripción de una instalación de prueba.
/api/developer/v1/sandboxes/:id/installations/:installationId/subscription/simulate-renewalSimula una renovación en una empresa de prueba; también simulate-payment-failure, simulate-trial-end y simulate-refund. Nada se cobra de verdad.
POST /listings/:id/test-install, instalar tu aplicación en una empresa de prueba, responde 403 APP_CATALOG_HUMAN_SESSION_REQUIRED con una clave: la instalación la hace una persona desde la consola.
Lo que una clave no puede llamar
| Rutas | Con una clave | Por qué |
|---|---|---|
/api/developer/v1/team | 403 API_KEY_PERMISSION_NOT_GRANTED o API_KEY_ROUTE_NOT_AVAILABLE | El equipo lo gestionan las personas. |
/api/developer/v1/account/fiscal-data | 403 API_KEY_PERMISSION_NOT_GRANTED | Los datos fiscales los decide una persona. |
/api/developer/v1/account/security, /account/close | 403 | La seguridad es de cada persona, y cerrar la cuenta, de la persona titular. |
/api/developer/v1/earnings, /payouts, /listings/:id/sales, /listings/:id/subscriptions | 403 API_KEY_ROUTE_NOT_AVAILABLE | El dinero, solo con una persona presente. |
/api/developer/v1/links | 403 API_KEY_ROUTE_NOT_AVAILABLE | La vinculación con tu empresa la empieza y la aprueba una persona. |
/api/developer/v1/approvals | 403 API_KEY_ROUTE_NOT_AVAILABLE | Confirmar una operación crítica es de una persona. |
Escrituras en /api/integrations/apps | 403 API_KEY_ROUTE_NOT_AVAILABLE | Crear o cambiar una aplicación fabrica credenciales que sobreviven a la clave. |
Errores
Una ruta de la consola responde como el resto de la API: errorCode y message en el cuerpo. Los que más verás con una clave:
API_KEY_PERMISSION_NOT_GRANTED: la clave no tiene marcado ese acceso. Lo que falta va enpermissions.API_KEY_RESPONSIBLE_PERMISSION_MISSING: lo tiene marcado, pero el rol de su persona responsable no lo permite.API_KEY_ROUTE_NOT_AVAILABLE: esa ruta no admite claves.APP_CATALOG_HUMAN_SESSION_REQUIRED,SANDBOX_HUMAN_SESSION_REQUIRED: lo hace una persona desde la consola.DEVELOPER_ACCOUNT_REQUIRED: la clave es de una empresa, no de una cuenta de desarrollador.
La tabla completa de errores de una petición con clave está en Hacer peticiones con una clave, y qué significa cada hallazgo de la comprobación, en Comprobar una clave.