API

Boldo expose une API REST complète sur /api/v1/. Utilisez-la pour intégrer Boldo avec des systèmes externes, automatiser des tâches récurrentes ou construire des outils sur votre base de connaissances.

Plan requis

L'accès API dépend de votre plan. Rendez-vous dans Organization → Developer pour vérifier votre accès.

Créer une clé API

1. Ouvrez Organization → Developer.
2. Cliquez sur "Create API Key".
3. Saisissez un nom et une description optionnelle.
4. Choisissez un type de permission : Viewer, Editor ou Admin.
5. Attribuez un ou plusieurs rôles pour définir le périmètre d'accès de la clé.
6. Cliquez sur "Create".
7. Copiez le secret immédiatement. Il ne s'affiche qu'une seule fois.

Chaque éditeur, administrateur ou propriétaire peut créer plusieurs clés API. Chaque clé possède son propre nom, niveau de permission et rôles associés.

Sécurité

Stockez le secret dans un coffre-fort sécurisé ou une variable d'environnement. Ne le versionnez jamais dans le contrôle de source. Si vous suspectez qu'une clé a été exposée, supprimez-la et créez-en une nouvelle.

Gérer les clés API

Rendez-vous dans Organization → Developer pour voir les clés API que vous êtes autorisé à gérer.

• Les éditeurs ne voient que leurs propres clés.
• Les administrateurs et propriétaires peuvent voir et gérer toutes les clés de l'organisation.

Depuis cet écran, vous pouvez modifier le nom, la description, le type de permission ou les rôles d'une clé. Les administrateurs et propriétaires peuvent aussi transférer une clé à un autre utilisateur. Vous pouvez supprimer les clés dont vous n'avez plus besoin.

Capacités de l'API

L'API V1 couvre les principales ressources avec lesquelles vous travaillez dans l'interface Boldo.

• Assets -- Créer, lire, mettre à jour et supprimer des actifs. Adressez un actif par son Boldo ID (l'UUID attribué à la création) ou, lorsque le type d'actif possède une propriété clé unique définie dans le métamodèle, par une clé composite au format {asset_type_key}:{unique_property_key}:{value}.
• Relationships -- Créer, lire et supprimer des relations entre actifs.
• Opérations en masse -- Créer jusqu'à 10 000 actifs ou 10 000 relations en une seule requête. Mettre à jour jusqu'à 10 000 actifs en une seule requête.
• Search -- Rechercher des actifs et des relations avec des filtres imbriqués et des groupes logiques sur n'importe quelle propriété.
• Analytics -- Exécuter des requêtes d'agrégation avec des mesures (count, count_distinct, sum, average) et regrouper ou ventiler les résultats par propriétés, attributs système ou types d'actifs liés.
• Metamodel -- Lire les types d'actifs, les définitions de propriétés et les types de relations.
• Administration -- Gérer les clés API (créer, lire, mettre à jour, supprimer). Lire les rôles, domaines d'accès et utilisateurs.

Modes de requête

L'API V1 propose deux façons d'interroger les actifs et les relations, selon la complexité de la requête.

Endpoints de liste

GET /assets et GET /relationships renvoient des listes paginées avec un filtrage par égalité uniquement. Passez les conditions en paramètres de query string, par exemple filter[asset_type_key]=server ou filter[properties.status]=active. Utilisez ces endpoints quand quelques conditions d'égalité suffisent.

La pagination utilise page[number] (par défaut 1) et page[size] (par défaut 50, maximum 100). Triez avec sort=field ou sort=-field pour l'ordre décroissant.

Endpoints de recherche

POST /search/assets et POST /search/relationships acceptent un corps JSON avec des conditions à opérateurs et des groupes AND/OR imbriqués. Utilisez-les quand les endpoints de liste sont trop restrictifs.

Les opérateurs disponibles sont :

• equals, not_equals
• greater_than, greater_than_or_equals, less_than, less_than_or_equals
• contains, not_contains, starts_with
• includes, not_includes (appartenance à une valeur multi-sélection)
• in, not_in (correspondance avec un tableau de valeurs)
• is_empty, is_not_empty

Extension des données liées

Les endpoints de liste et de recherche acceptent include pour ramener les données liées dans la réponse en un seul aller-retour :

• include=relationships -- attache les relations de l'actif avec leurs IDs uniquement
• include=relationships,relationships.related_asset -- étend aussi l'actif lié sur chaque relation
• include=relationships,relationships.related_asset.properties -- inclut également les valeurs de propriétés de l'actif lié

Sur les endpoints de relations, utilisez include=source_asset ou include=target_asset pour étendre l'une ou l'autre extrémité d'une relation, et ajoutez .properties pour récupérer leurs valeurs de propriétés.

Les relations incluses peuvent être paginées, filtrées et triées indépendamment. Sur les endpoints de liste, utilisez relationships_page, relationships_filter et relationships_sort. Sur les endpoints de recherche, passez un bloc relationships dans le corps de la requête avec la même structure page, filter et sort que la requête principale.

Opérations en masse

POST /bulk/assets, PATCH /bulk/assets et POST /bulk/relationships acceptent jusqu'à 10 000 éléments par requête.

Les requêtes en masse sont tout-ou-rien. Si un seul élément échoue à la validation, toute la requête est rejetée et rien n'est écrit. Cela garde l'inventaire dans un état cohérent quand un lot est partiellement erroné.

Chaque élément peut porter une valeur client_ref optionnelle. Cette valeur est renvoyée dans la réponse à côté de l'ID créé ou mis à jour, ce qui permet de relier les Boldo IDs à vos enregistrements source sans deuxième appel. C'est particulièrement utile pour les imports idempotents.

Synchronisation scopée des relations embarquées

Quand vous créez ou mettez à jour un actif avec des relations embarquées, chaque couple (direction, type de relation) est remplacé intégralement. Envoyer related_assets: [] pour une direction et un type donnés supprime toutes les relations existantes de ce type sur cet actif.

Ce comportement est important sur les requêtes de mise à jour : omettez un couple direction/type si vous ne voulez pas toucher à ses relations, et incluez-le uniquement quand vous voulez remplacer l'ensemble. Pour ajouter ou retirer une seule relation sans toucher au reste, utilisez plutôt les endpoints dédiés /relationships ou /bulk/relationships.

Formats de date

created_at et updated_at sont des timestamps : ils enregistrent le moment où un changement a eu lieu, à la seconde près, en ISO 8601 UTC (YYYY-MM-DDTHH:mm:ssZ).

Les propriétés de type date définies dans le métamodèle décrivent un jour, pas un moment -- une mise en production, un début de contrat, une date de revue -- et utilisent YYYY-MM-DD. L'API rejette les timestamps complets sur ces champs.

Spécification OpenAPI

L'API Boldo suit le standard OpenAPI. OpenAPI est un format largement adopté qui décrit les API REST de manière lisible par les machines -- endpoints, paramètres, corps de requête et schémas de réponse sont tous définis dans un seul fichier.

Cela signifie que vous pouvez utiliser la spécification avec n'importe quel outil compatible OpenAPI. Par exemple :

• Postman ou Insomnia -- importez la spec pour obtenir une collection prête à l'emploi de tous les endpoints
• Générateurs de code -- générez un client API typé dans le langage de votre choix (TypeScript, Python, Go, etc.)
• Pipelines CI -- validez les payloads contre la spec avant de les envoyer
• Assistants IA -- fournissez la spec à un LLM pour l'aider à écrire des scripts d'intégration

Documentation interactive

Boldo génère également une page de documentation API interactive directement à partir de la spec. La page regroupe tous les endpoints V1 par ressource (Assets, Relationships, Bulk, Search, Analytics, etc.) pour que vous puissiez naviguer, vous authentifier et tester vos requêtes sans quitter le navigateur.

Spec de base vs Spec typée

Deux spécifications sont disponibles, chacune en JSON et YAML :

• Spec de base sur /api/v1/openapi/base.json (ou .yaml) -- décrit tous les endpoints avec des schémas génériques. Elle ne nécessite pas d'authentification et fonctionne pour n'importe quelle organisation. Utilisez-la pour découvrir l'API, configurer un client ou importer dans Postman.
• Spec typée sur /api/v1/openapi/typed.json (ou .yaml) -- nécessite une authentification. Elle inclut des schémas qui reflètent votre métamodèle réel : types d'actifs, noms de propriétés, valeurs d'énumération et types de relations font partie de la spec. Utilisez-la quand vous voulez des schémas de requête et de réponse qui correspondent à votre base de connaissances spécifique, par exemple pour générer un client entièrement typé.

Authentification et permissions

Authentifiez chaque requête en envoyant votre clé API comme jeton Bearer dans l'en-tête Authorization :

Authorization: Bearer YOUR_API_KEY

La clé hérite du type de permission et des rôles que vous avez assignés lors de sa création. Une clé avec la permission Viewer ne peut que lire les données. Une clé Editor peut lire et écrire. Une clé Admin dispose d'un accès complet.

Vous pouvez déléguer l'accès en toute sécurité en créant une clé limitée à un ensemble restreint de rôles. Cela limite ce que la clé peut voir et modifier, même si le type de permission est large.

Les administrateurs peuvent également déléguer une clé à un autre utilisateur, ce qui est utile lorsqu'un utilisateur possédant une clé de production quitte l'organisation. Le type de permission effectif est toujours le minimum entre celui de la clé et celui de l'utilisateur. Par exemple, une clé administrateur transférée à un éditeur fonctionnera comme une clé éditeur. Un éditeur ne peut attribuer que les rôles qu'il possède déjà.

Limitation de débit

Les requêtes API sont limitées en débit par organisation, et le quota est partagé entre toutes les clés API émises par l'organisation. Si vous recevez une réponse 429 avec rate_limit_exceeded, attendez avant de réessayer.

Quand utiliser l'API

Utilisez l'API lorsque vous avez besoin d'un travail répétable ou programmatique sur la base de connaissances. Les cas typiques incluent l'intégration de Boldo avec un autre système, l'exécution de synchronisations récurrentes, l'automatisation de mises à jour et la construction de scripts ou d'outils internes.

Utilisez plutôt Importer un fichier lorsque le besoin est un import en masse ponctuel géré par des utilisateurs métier.

Utilisez l'interface lorsque vous mettez à jour quelques actifs manuellement, ajustez le métamodèle ou exportez un CSV ou une image ponctuels.