API pública de Kabeen
Una API REST para leer y gestionar el inventario de activos de TI de su espacio de trabajo desde sus propias herramientas y scripts
La API pública de Kabeen es una API REST para integraciones que necesitan leer o gestionar el inventario de activos de TI de un espacio de trabajo: aplicaciones, servidores, redes, routers, puestos de trabajo, objetos de datos, contratos, estructura de la organización, personas, anuncios e historial de auditoría. Está diseñada para herramientas externas: sincronizaciones de CMDB, cuadros de mando personalizados, puentes ITSM, pipelines de reporting y scripts de automatización internos que necesitan acceso programático a los mismos datos que ve un administrador en el producto Kabeen.
Esta es la versión 1.0.0, la primera publicación pública de la API.
URL base y versionado
https://app.kabeen.io/public/v1Sustituya app.kabeen.io por su propio host si aloja Kabeen usted mismo. El segmento de ruta v1 es la versión de la API: los cambios incompatibles se publicarán bajo un nuevo prefijo de versión en lugar de modificar v1 sobre la marcha.
Todos los cuerpos de petición y de respuesta son JSON. Todos los endpoints leen y escriben sobre un único espacio de trabajo: aquel al que está vinculada la clave de API. No hay forma de dirigirse a otro espacio de trabajo con la misma clave.
Autenticación
Cada petición se autentica con una clave de API vinculada al espacio de trabajo, enviada como Authorization: Bearer kbn_live_... o como X-Api-Key: kbn_live_.... El espacio de trabajo está ligado a la propia clave: nunca se pasa en la ruta ni en el cuerpo de la petición.
Las claves llevan un conjunto de scopes de permisos (p. ej. applications:read, contracts:add), y cada endpoint documenta el scope exacto que requiere. Llame a GET /public/v1/me para introspeccionar una clave: devuelve el espacio de trabajo al que pertenece la clave, los metadatos de la propia clave y los scopes que otorga.
Consulte Autenticación para la guía completa, incluido cómo se emiten, rotan y revocan las claves.
Áreas de recursos
La API se organiza en las siguientes áreas de recursos, con aproximadamente 200 operaciones:
| Área | Descripción | Scope(s) principal(es) |
|---|---|---|
| Introspección | Describe la clave de API presentada: espacio de trabajo, metadatos, scopes otorgados. | cualquier clave válida |
| Aplicaciones | Inventario de aplicaciones, detalle enriquecido y sub-recursos (uso, flujos, tecnologías, contratos, comentarios, responsables, etiquetas, equipos, ciclo de vida, documentos, campos personalizados, métricas de experiencia, capacidades funcionales). | applications:read / :add / :edit / :delete / :comment |
| Servidores | Servidores de infraestructura manuales y reportados por agente, con responsables, etiquetas, interfaces, métricas y aplicaciones vinculadas. | infrastructure:read / :add / :edit / :delete |
| Redes | Redes y sus routers conectados. | infrastructure:read / :add / :edit / :delete |
| Routers | Dispositivos de red: router, firewall, switch, punto de acceso. | infrastructure:read / :add / :edit / :delete |
| Puestos de trabajo y software | Puestos de trabajo reportados por agente, programas instalados, inventario de software y estado de despliegue de los agentes. | infrastructure:read, agents:read |
| Datos | Objetos de datos (activos de información) y sus vínculos con aplicaciones. | data:read / :add / :edit / :delete |
| Catálogo | Búsqueda en el catálogo global de aplicaciones y aplicaciones autodescubiertas. | applications:read |
| Contratos | Contratos de aplicaciones, aplanados a nivel del espacio de trabajo. | contracts:read / :add / :edit / :delete |
| Taxonomía | Categorías y etiquetas de aplicaciones. | categories:*, tags:* |
| Organización | Árbol de la organización y equipos (unidades de negocio). | organisation:read / :add / :edit / :delete |
| Personas | Usuarios finales rastreados (con métricas de experiencia) y miembros del espacio de trabajo. | users:read, members:read |
| Espacio de trabajo | El espacio de trabajo (tenant) al que está vinculada la clave. | tenant:read / :edit |
| Anuncios | Anuncios del espacio de trabajo. | announces:read / :add / :edit / :delete |
| Registro de auditoría | Eventos de auditoría del espacio de trabajo, paginados por cursor. | audit_log:read |
| Cuadros de mando, insights y diagramas | Cuadros de mando agregados (finanzas, uso, operaciones, arquitectura, tecnología, puestos de trabajo), insights de salud y diagramas de arquitectura. | *_dashboard:read, *_diagram:read, applications:read |
La lista completa de endpoints, con sus entradas y salidas, está en la Referencia de endpoints.
Convenciones
- JSON en todas partes: cada cuerpo de petición y de respuesta es JSON (
application/json). - UUID y fechas como cadenas: los identificadores de recursos son cadenas UUID; las fechas y marcas de tiempo son cadenas ISO-8601.
- Paginación por offset: los endpoints de listado aceptan
limit(1–200, por defecto 50) yoffset(por defecto 0) y devuelven un sobre de la forma{ "data": [...], "pagination": { "limit", "offset", "total" } }. El registro de auditoría es la única excepción, con paginación por cursor. Consulte Paginación y errores. - Errores uniformes: cada cuerpo de respuesta 4xx/5xx tiene la misma forma:
{ "code", "message", "status" }. - Auditado: cada llamada a la API pública se escribe en el registro de auditoría del espacio de trabajo, con la clave de API como actor.
- Sin webhooks: en esta versión la API funciona solo por sondeo (polling); no existe mecanismo de eventos/webhooks. El registro de auditoría es lo más parecido a un flujo de cambios — consulte Paginación y errores para las pautas de sondeo.
¿API pública o servidor MCP?
Ambas superficies exponen el mapa del espacio de trabajo. Elija en función del consumidor:
- La API pública (esta sección) es para integraciones deterministas y programáticas: scripts, sincronizaciones, pipelines. Se autentica con una clave de API que actúa como identidad de servicio.
- El servidor MCP es para asistentes y agentes de IA. Se autentica mediante OAuth como un miembro humano y hereda los permisos de ese miembro.
Próximos pasos
- Inicio rápido — realice su primera llamada autenticada en cinco minutos.
- Autenticación — claves de API, scopes y
/me. - Referencia de endpoints — todos los endpoints con sus entradas y salidas.