Référence API
Canopy expose une API REST complète qui alimente tout ce que vous pouvez faire dans l'interface web. Vous pouvez l'utiliser pour automatiser les mises à jour d'inventaire, intégrer des pipelines CI/CD, créer des tableaux de bord personnalisés ou extraire des données d'architecture d'entreprise vers d'autres outils (BI, GRC, ITSM, tableurs).
La spécification OpenAPI 3.1 complète est disponible dans la section Points de terminaison API de la barre latérale — chaque point de terminaison, paramètre et forme de réponse, régénérée à partir du code source du backend à chaque release.
URL de base
Tous les points de terminaison de l'API se trouvent sous le préfixe /api/v1. L'URL de votre environnement Canopy suit le modèle :
https://{votre-slug}-canopy.rhizo-tech.org/api/v1
Remplacez {votre-slug} par le slug de votre organisation, qui apparaît dans votre compte Rhizo et dans l'URL que vous utilisez pour accéder à Canopy.
La seule exception est le point de terminaison de santé, monté à /api/health (sans préfixe de version).
Référence API interactive
La spécification OpenAPI 3.1 complète est disponible dans la section Points de terminaison API de la barre latérale. Chaque page de point de terminaison comprend un playground interactif où vous pouvez saisir votre bearer token et exécuter des requêtes en direct contre votre environnement Canopy.
La spécification brute est également téléchargeable pour les générateurs de code :
https://docs.rhizo-tech.org/api/openapi.json
Pour utiliser le playground interactif, ouvrez n'importe quelle page de point de terminaison dans la section Points de terminaison API de la barre latérale, saisissez votre bearer token dans le champ Authorization, remplissez les paramètres et cliquez sur Send.
Authentification
Tous les points de terminaison sauf /auth/*, le contrôle de santé et les portails web publics nécessitent un JSON Web Token envoyé dans l'en-tête Authorization :
Authorization: Bearer <access_token>
Obtenir un token
POST /api/v1/auth/login avec votre e-mail et votre mot de passe :
curl -X POST https://{votre-slug}-canopy.rhizo-tech.org/api/v1/auth/login \
-H "Content-Type: application/json" \
La réponse contient un access_token :
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "bearer"
}
Les tokens sont valides 24 heures. Utilisez POST /api/v1/auth/refresh pour prolonger une session sans ressaisir les identifiants.
Si votre organisation utilise l'authentification unique, vous ne pouvez pas vous connecter avec un e-mail et un mot de passe via l'API. Demandez à votre administrateur Canopy de créer un compte de service dédié avec un mot de passe local pour l'automatisation.
Utiliser le token
curl https://{votre-slug}-canopy.rhizo-tech.org/api/v1/cards \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Permissions
L'API applique les mêmes règles RBAC que l'interface web. Chaque point de terminaison mutant vérifie à la fois le rôle applicatif de l'appelant et tous les rôles de parties prenantes qu'il détient sur la fiche concernée. Il n'y a pas de « permissions API » séparées ni de contournements pour les comptes de service – les scripts d'automatisation s'exécutent avec les permissions de l'utilisateur dont ils utilisent le token.
Si une requête échoue avec 403 Forbidden, le token est valide mais l'utilisateur ne dispose pas de la permission requise. Consultez la page Utilisateurs & Rôles pour le registre des permissions.
Groupes de points de terminaison courants
La référence dans la barre latérale est la source complète de vérité ; le tableau ci-dessous est une carte rapide des groupes les plus utilisés :
| Préfixe | Objectif |
|---|---|
/auth | Connexion, inscription, callback SSO, renouvellement de token, informations sur l'utilisateur actuel |
/cards | CRUD sur les fiches (l'entité principale), hiérarchie, historique, approbation, export CSV |
/relations | CRUD sur les relations entre fiches |
/metamodel | Types de fiches, champs, sections, sous-types, types de relations |
/reports | KPI du tableau de bord, portefeuille, matrice, cycle de vie, dépendances, coûts, qualité des données |
/bpm | Gestion des processus métier – diagrammes, éléments, versions de flux, évaluations |
/ppm | Gestion du portefeuille de projets – initiatives, rapports de statut, WBS, tâches, coûts, risques |
/turbolens | Analyse pilotée par l'IA (fournisseurs, doublons, IA d'architecture) |
/risks | Registre des risques EA (TOGAF Phase G) |
/diagrams | Diagrammes DrawIO |
/soaw | Documents Statement of Architecture Work |
/adr | Architecture Decision Records |
/users, /roles | Administration des utilisateurs et des rôles (administrateur uniquement) |
/settings | Paramètres de l'application (logo, devise, SMTP, IA, bascules de modules) |
/servicenow | Synchronisation bidirectionnelle CMDB ServiceNow |
/events, /notifications | Piste d'audit et notifications utilisateur (incl. flux SSE) |
Pagination, filtrage et tri
Les points de terminaison de liste acceptent un ensemble cohérent de paramètres de requête :
| Paramètre | Description |
|---|---|
page | Numéro de page (base 1) |
page_size | Éléments par page (défaut 50, max 200) |
sort_by | Champ selon lequel trier (par ex. name, updated_at) |
sort_dir | asc ou desc |
search | Filtre en texte libre (là où pris en charge) |
Les filtres spécifiques aux ressources sont documentés par point de terminaison dans la référence de la barre latérale (par ex. /cards accepte type, status, parent_id, approval_status).
Événements en temps réel (Server-Sent Events)
GET /api/v1/events/stream est une connexion SSE de longue durée qui envoie des événements au fur et à mesure qu'ils se produisent (fiche créée, mise à jour, approuvée, etc.). L'interface web l'utilise pour actualiser les badges et les listes sans interrogation. Tout client HTTP prenant en charge SSE peut s'abonner – utile pour créer des tableaux de bord en temps réel ou des ponts de notification externes.
Génération de code
Comme l'API est entièrement décrite par OpenAPI 3.1, vous pouvez générer des clients typés dans n'importe quel langage majeur :
# Télécharger le schéma
curl https://docs.rhizo-tech.org/api/openapi.json -o canopy-openapi.json
# Générer un client Python
openapi-generator-cli generate \
-i canopy-openapi.json \
-g python \
-o ./canopy-client-py
# …ou TypeScript, Go, Java, C#, etc.
Pour l'automatisation Python, le chemin le plus simple est généralement httpx ou requests avec des appels écrits à la main – l'API est assez petite pour qu'un générateur soit rarement rentable.
Limitation du débit
Les points de terminaison sensibles à l'authentification (connexion, inscription, réinitialisation de mot de passe) sont limités en débit pour se protéger contre les attaques par force brute. Les autres points de terminaison ne sont pas actuellement limités en débit ; pour les scripts d'automatisation intensifs, implémentez une limitation côté client.
Versionnage et stabilité
- L'API est versionnée via le préfixe
/api/v1. Un changement cassant introduirait/api/v2en parallèle. - Dans
v1, les changements additifs (nouveaux points de terminaison, nouveaux champs optionnels) peuvent être livrés dans des releases mineures et de patch. Les suppressions ou changements de contrat sont réservés à une évolution de version majeure. - La version actuelle est signalée par
GET /api/healthpour que vous puissiez détecter les mises à niveau depuis l'automatisation.
Résolution des problèmes
| Problème | Solution |
|---|---|
401 Unauthorized | Le token est absent, malformé ou expiré. Authentifiez-vous à nouveau via /auth/login ou /auth/refresh. |
403 Forbidden | Le token est valide mais l'utilisateur ne dispose pas de la permission requise. Vérifiez le rôle de l'utilisateur dans Utilisateurs & Rôles. |
422 Unprocessable Entity | La validation Pydantic a échoué. Le corps de la réponse liste les champs invalides et la raison. |