Referencia de la API
Canopy expone una API REST completa que hace posible todo lo que puede hacer en la interfaz web. Puede usarla para automatizar actualizaciones del inventario, integrarla con canalizaciones CI/CD, crear paneles de control personalizados o extraer datos de AE hacia otras herramientas (BI, GRC, ITSM, hojas de cálculo).
La especificación completa de OpenAPI 3.1 está disponible en la sección Endpoints de API de la barra lateral — cada endpoint, parámetro y esquema de respuesta, regenerado desde el código fuente del backend en cada lanzamiento.
URL base
Todos los endpoints de la API se encuentran bajo el prefijo /api/v1. La URL de su entorno Canopy sigue el patrón:
https://{su-slug}-canopy.rhizo-tech.org/api/v1
Reemplace {su-slug} por el slug de su organización, que aparece en su cuenta de Rhizo y en la URL que usa para acceder a Canopy.
La única excepción es el endpoint de estado de salud, que está montado en /api/health (sin prefijo de versión).
Referencia API interactiva
La especificación completa de OpenAPI 3.1 está disponible en la sección Endpoints de API de la barra lateral. Cada página de endpoint incluye un playground interactivo donde puede introducir su bearer token y ejecutar solicitudes en vivo contra su entorno Canopy.
La especificación sin procesar también está disponible para descarga para generadores de código:
https://docs.rhizo-tech.org/api/openapi.json
Para usar el playground interactivo, abra cualquier página de endpoint en la sección Endpoints de API de la barra lateral, introduzca su bearer token en el campo Authorization, rellene los parámetros y haga clic en Send.
Autenticación
Todos los endpoints excepto /auth/*, el chequeo de estado y los portales web públicos requieren un JSON Web Token enviado en la cabecera Authorization:
Authorization: Bearer <access_token>
Obtener un token
POST /api/v1/auth/login con su correo electrónico y contraseña:
curl -X POST https://{su-slug}-canopy.rhizo-tech.org/api/v1/auth/login \
-H "Content-Type: application/json" \
La respuesta contiene un access_token:
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "bearer"
}
Los tokens son válidos durante 24 horas. Use POST /api/v1/auth/refresh para extender una sesión sin volver a introducir las credenciales.
Si su organización usa inicio de sesión único, no puede autenticarse con correo electrónico y contraseña a través de la API. Solicite a su administrador de Canopy que cree una cuenta de servicio dedicada con contraseña local para la automatización.
Usar el token
curl https://{su-slug}-canopy.rhizo-tech.org/api/v1/cards \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Permisos
La API aplica las mismas reglas RBAC que la interfaz web. Cada endpoint de mutación comprueba tanto el rol de aplicación del solicitante como los roles de partes interesadas que tiene sobre la tarjeta afectada. No existen «permisos de API» separados ni excepciones para cuentas de servicio — los scripts de automatización funcionan con los permisos del usuario cuyo token utilizan.
Si una solicitud falla con 403 Forbidden, el token es válido pero el usuario no tiene el permiso requerido. Consulte la página Usuarios y roles para el registro de permisos.
Grupos de endpoints habituales
La referencia en la barra lateral es la fuente completa de verdad; la tabla siguiente es un mapa rápido de los grupos más utilizados:
| Prefijo | Propósito |
|---|---|
/auth | Inicio de sesión, registro, callback SSO, renovación de token, información del usuario actual |
/cards | CRUD sobre tarjetas (la entidad principal), jerarquía, historial, aprobación, exportación CSV |
/relations | CRUD sobre relaciones entre tarjetas |
/metamodel | Tipos de tarjeta, campos, secciones, subtipos, tipos de relación |
/reports | KPIs del panel, portafolio, matriz, ciclo de vida, dependencias, coste, calidad de datos |
/bpm | Gestión de procesos de negocio — diagramas, elementos, versiones de flujo, evaluaciones |
/ppm | Gestión del portafolio de proyectos — iniciativas, informes de estado, EDT, tareas, costes, riesgos |
/turbolens | Análisis basado en IA (proveedores, duplicados, arquitectura IA) |
/risks | Registro de riesgos de AE (Fase G de TOGAF) |
/diagrams | Diagramas DrawIO |
/soaw | Documentos de Declaración de Trabajo de Arquitectura |
/adr | Registros de decisiones de arquitectura |
/users, /roles | Administración de usuarios y roles (solo administradores) |
/settings | Configuración de la aplicación (logotipo, moneda, SMTP, IA, activación de módulos) |
/servicenow | Sincronización bidireccional con ServiceNow CMDB |
/events, /notifications | Registro de auditoría y notificaciones de usuario (incluye flujo SSE) |
Paginación, filtrado y ordenación
Los endpoints de lista aceptan un conjunto coherente de parámetros de consulta:
| Parámetro | Descripción |
|---|---|
page | Número de página (basado en 1) |
page_size | Elementos por página (por defecto 50, máximo 200) |
sort_by | Campo por el que ordenar (por ejemplo, name, updated_at) |
sort_dir | asc o desc |
search | Filtro de texto libre (donde se admite) |
Los filtros específicos de cada recurso están documentados en cada endpoint en la referencia de la barra lateral (por ejemplo, /cards acepta type, status, parent_id, approval_status).
Eventos en tiempo real (Server-Sent Events)
GET /api/v1/events/stream es una conexión SSE de larga duración que envía eventos según van ocurriendo (tarjeta creada, actualizada, aprobada, etc.). La interfaz web la usa para actualizar insignias y listas sin necesidad de sondear. Cualquier cliente HTTP que admita SSE puede suscribirse — útil para crear paneles en tiempo real o puentes de notificación externos.
Generación de código
Dado que la API está completamente descrita por OpenAPI 3.1, puede generar clientes con tipos seguros en cualquier lenguaje principal:
# Descargar el esquema
curl https://docs.rhizo-tech.org/api/openapi.json -o canopy-openapi.json
# Generar un cliente Python
openapi-generator-cli generate \
-i canopy-openapi.json \
-g python \
-o ./canopy-client-py
# …o TypeScript, Go, Java, C#, etc.
Para la automatización en Python, el camino más sencillo suele ser httpx o requests con llamadas escritas a mano — la API es lo suficientemente pequeña como para que un generador raramente valga la pena como dependencia.
Límite de velocidad
Los endpoints sensibles para la autenticación (inicio de sesión, registro, restablecimiento de contraseña) tienen límite de velocidad para proteger contra ataques de fuerza bruta. El resto de endpoints no tienen límite de velocidad actualmente; para scripts de automatización intensivos, implemente la limitación en el lado del cliente.
Versionado y estabilidad
- La API está versionada a través del prefijo
/api/v1. Un cambio incompatible introduciría/api/v2junto a él. - Dentro de
v1, los cambios aditivos (nuevos endpoints, nuevos campos opcionales) pueden aparecer en versiones menores y de parche. Las eliminaciones o cambios de contrato están reservados para un salto de versión mayor. - La versión actual la informa
GET /api/health, lo que permite detectar actualizaciones desde la automatización.
Resolución de problemas
| Problema | Solución |
|---|---|
401 Unauthorized | El token falta, está mal formado o ha expirado. Vuelva a autenticarse mediante /auth/login o /auth/refresh. |
403 Forbidden | El token es válido pero el usuario no tiene el permiso requerido. Compruebe el rol del usuario en Usuarios y roles. |
422 Unprocessable Entity | La validación de Pydantic ha fallado. El cuerpo de la respuesta indica qué campos son inválidos y por qué. |