Cybee > documents > API > Utilisation des API
View Categories

Utilisation des API

Cybee API – Vue d’ensemble #

  • Version OpenAPI : 3.1.0

  • Version Cybee API : 0.18.12

  • Auth :

    • Bearer Token

    • ou Authenticate via Web (PKCE)

Les APIs de Cybee sont organisées par domaines via les tags :

  • storage-account, storage-destination, storage-repository

  • plans-backup, plans-restore, plans-schedule

  • agents

  • cmdb

Domaine Storage – Comptes, destinations & repositories #

1. Storage Accounts (storage-account) #

Objectif du domaine #

Gérer les comptes de stockage (ex : compte S3, provider, credentials) qui serviront ensuite aux destinations et repositories.

Ressources principales #

  • StorageAccount

  • StorageAccountCreate

  • StorageAccountUpdate

  • Enum S3Provider (type de provider S3)

Endpoints #

Lister les comptes de stockage #

  • GET /storage/storage-account/

    • But : liste paginée de tous les comptes de stockage configurés.

    • Filtres (query) :

      • page, per_page, order_by

      • id (uuid)

      • name (string)

      • provider (S3Provider)

    • Réponse : Page_StorageAccount_ (pagination + items).

Créer un compte de stockage #

  • POST /storage/storage-account/

    • But : créer un nouveau compte de stockage (credentials, endpoint, provider…).

    • Body : StorageAccountCreate

    • Réponse : 204 No Content si OK.

Récupérer un compte de stockage #

  • GET /storage/storage-account/{storage_account_id}/

    • But : récupérer le détail d’un compte (provider, nom, etc.).

    • Path : storage_account_id (uuid)

    • Réponse : StorageAccount

Mettre à jour un compte de stockage #

  • PUT /storage/storage-account/{storage_account_id}/

    • But : modifier un compte existant.

    • Path : storage_account_id (uuid)

    • Body : StorageAccountUpdate

    • Réponse : 204 No Content

Supprimer un compte de stockage #

  • DELETE /storage/storage-account/{storage_account_id}/

    • But : supprimer / désactiver un compte de stockage.

    • Path : storage_account_id (uuid)

    • Réponse : 204 No Content

2. Storage Destinations (storage-destination) #

Objectif du domaine #

Définir les destinations de stockage (dossiers / préfixes S3, base paths…) rattachées à un StorageAccount.
C’est là qu’on précise où les repos sont physiquement stockés.

Ressources principales #

  • StorageDestination

  • StorageDestinationCreate

  • StorageDestinationUpdate

Endpoints #

Lister les destinations #

  • GET /storage/storage-destination/

    • Filtres :

      • page, per_page, order_by

      • id (uuid)

      • name (NonEmptyStr)

      • base_path (NonEmptyStr)

      • storage_account_id (uuid)

    • Réponse : Page_StorageDestination_

Créer une destination #

  • POST /storage/storage-destination/

    • Body : StorageDestinationCreate

    • Réponse : 200 avec un StorageDestination créé.

Lire / modifier / supprimer une destination #

  • GET /storage/storage-destination/{storage_destination_id}/ → StorageDestination

  • PATCH /storage/storage-destination/{storage_destination_id}/

    • Body : StorageDestinationUpdate

    • Réponse : 204

  • DELETE /storage/storage-destination/{storage_destination_id}/

    • Réponse : 204

3. Storage Repositories (storage-repository) #

Objectif du domaine #

Gérer les repositories Restic qui servent de backend pour les plans de sauvegarde / restauration.

Ressources principales #

  • Repository

  • RepositoryCreate

  • RepositoryUpdate

  • RepositoryMaintenance

  • Enums : RepositoryStatusEnum, ResticVersionEnum, MaintenanceType

Endpoints #

Lister les repositories #

  • GET /storage/repository/

    • Filtres :

      • page, per_page, order_by

      • id, name, slug

      • status (RepositoryStatusEnum)

      • storage_destination_id (uuid)

      • version (ResticVersionEnum)

    • Réponse : Page_Repository_

Créer un repository #

  • POST /storage/repository/

    • Body : RepositoryCreate

    • Réponse : 204

Lire / modifier / supprimer un repository #

  • GET /storage/repository/{repository_id}/ → Repository

  • PATCH /storage/repository/{repository_id}/

    • Body : RepositoryUpdate

    • Réponse : 204

  • DELETE /storage/repository/{repository_id}/ → 204

Maintenance d’un repository #

  • GET /storage/repository/{repository_id}/maintenance/

    • But : lire le paramétrage de maintenance (check / prune, planning, etc.).

    • Réponse : RepositoryMaintenance

  • POST /storage/repository/{repository_id}/maintenance/{maintenance_type}/

    • But : créer ou modifier la config de maintenance pour un type donné.

    • maintenance_type : enum MaintenanceType (check ou prune)

    • Body : RepositoryMaintenanceCreateUpdate

    • Réponse : RepositoryMaintenance

  • DELETE /storage/repository/{repository_id}/maintenance/{maintenance_type}/

    • But : désactiver / supprimer la maintenance pour ce type.

    • Réponse : 204

  • GET /storage/repository/{repository_id}/maintenance/{maintenance_type}/execute/

    • But : lancer manuellement la maintenance (check ou prune) sur ce repo.

    • Réponse : 200 (corps vide ou minimal).

Domaine Plans de sauvegarde (plans-backup) #

Ce domaine couvre les plans de sauvegarde Restic (image & fichiers), leur exécution, leur historique, et leur association à des agents / schedules.

1. Historique global des sauvegardes #

Lister tout l’historique des sauvegardes #

  • GET /plan/backup/history/

    • Liste paginée des exécutions de plans de backup (tous types).

    • Filtres : id, plan_id, repository_id, agent_id, status (PlanStatus), finished_at.

    • Réponse : Page_BackupPlanRun_ (items de type BackupPlanRun).

Lister uniquement les dernières exécutions #

  • GET /plan/backup/history/latest/

    • Même filtres, mais ne retourne que la dernière exécution par plan.

2. Plans de sauvegarde Image #

Lister les plans d’image #

  • GET /plan/backup/image/

    • But : récupérer les plans de sauvegarde image configurés.

    • Filtres :

      • id, name, repo_id (uuid)

      • schedule_enabled (bool)

      • linked_agents_contains (liste d’agent_id)

    • Réponse : Page_ImageBackupPlan_

    • Les items contiennent notamment :

      • config : options Restic (sans source_paths, car l’image utilise extension.partitions)

      • extension.partitions : partitions disque à sauvegarder

      • retention_config : stratégie de rétention

      • schedule_enabled, schedule_configs

      • affected_agents, etc. (voir description détaillée dans l’OpenAPI).

Créer un plan d’image #

  • POST /plan/backup/image/

    • Body : ImageBackupPlanCreate

    • Points importants :

      • name (obligatoire)

      • repo_id (obligatoire)

      • config (ResticBackup, sans source_paths)

      • extension.partitions obligatoire (cartographie des partitions)

      • schedule_enabled / schedule_config_id

      • scripts pre_script / post_script possibles.

    • Réponse : 204

Lire / mettre à jour / supprimer un plan d’image #

  • GET /plan/backup/image/{plan_id}/ → ImageBackupPlan

  • PUT /plan/backup/image/{plan_id}/

    • Body : ImageBackupPlanUpdate (tous champs optionnels, update partiel).

    • Attention : si config fourni → toujours sans source_paths.

    • Réponse : 204

  • DELETE /plan/backup/image/{plan_id}/ → 204

Exécuter un plan d’image #

  • GET /plan/backup/image/{plan_id}/execute/

    • Lancement d’une exécution du plan.

    • Réponse : 202 Accepted (tâche asynchrone).

Historique d’un plan d’image #

  • GET /plan/backup/image/{plan_id}/history/

    • Historique paginé des exécutions pour ce plan uniquement.

    • Réponse : Page_BackupPlanRun_.

3. Plans de sauvegarde Fichiers #

Lister les plans fichier #

  • GET /plan/backup/file/

    • Filtres similaires à l’image : id, name, repo_id, schedule_enabled, linked_agents_contains.

    • Réponse : Page_FileBackupPlan_.

    • Différence clé : config.source_paths obligatoire (un ou plusieurs chemins absolus).

Créer un plan fichier #

  • POST /plan/backup/file/

    • Body : FileBackupPlanCreate

    • Obligations :

      • name, repo_id

      • config.source_paths (chemins absolus)

      • exclusions possibles : exclude, iexclude, exclude_caches, exclude_if_present, exclude_larger_than

      • scripts pre_script / post_script.

    • Réponse : 204

Lire / mettre à jour / supprimer un plan fichier #

  • GET /plan/backup/file/{plan_id}/ → FileBackupPlan

  • PUT /plan/backup/file/{plan_id}/

    • Body : FileBackupPlanUpdate

    • Si config fourni → doit contenir source_paths et chemins absolus.

    • Réponse : 204

  • DELETE /plan/backup/file/{plan_id}/ → 204

Exécuter un plan fichier #

  • GET /plan/backup/file/{plan_id}/execute/

    • Lance le plan manuellement.

    • Réponse : 202 Accepted.

Historique d’un plan fichier #

  • GET /plan/backup/file/{plan_id}/history/

    • Historique paginé des exécutions.

    • Réponse : Page_BackupPlanRun_.

4. Assignation de schedules & agents à un plan (backup) #

Ces endpoints sont génériques pour tout plan de backup (image ou fichier), identifiés par plan_id.

Associer / retirer un schedule #

  • POST /plan/backup/{plan_id}/assign-schedule/{schedule_id}/

    • Associe un calendrier d’exécution à un plan.

    • Réponse : 204.

  • POST /plan/backup/{plan_id}/remove-schedule/{schedule_id}/

    • Retire le calendrier d’un plan.

    • Réponse : 204.

Associer / retirer un agent #

  • POST /plan/backup/{plan_id}/assign-agent/{agent_id}/

    • Lie un agent (machine) à un plan de backup.

    • Réponse : 204.

  • POST /plan/backup/{plan_id}/remove-agent/{agent_id}/

    • Délie l’agent du plan.

    • Réponse : 204.

Domaine Plans de restauration (plans-restore) #

Miroir fonctionnel des plans de sauvegarde, mais pour la restauration (image & fichiers).

1. Historique global des restaurations #

  • GET /plan/restore/history/

    • Historique global des exécutions de plans de restore.

    • Filtres : id, plan_id, repository_id, agent_id, status, finished_at.

    • Réponse : Page_RestorePlanRun_.

  • GET /plan/restore/history/latest/

    • Même chose, mais uniquement la dernière exécution par plan.

2. Plans de restauration Image #

  • GET /plan/restore/image/ — lister (Page_ImageRestorePlan_)

  • POST /plan/restore/image/ — créer (ImageRestorePlanCreate)

  • GET /plan/restore/image/{plan_id}/ — lire (ImageRestorePlan)

  • PUT /plan/restore/image/{plan_id}/ — mettre à jour (ImageRestorePlanUpdate)

  • DELETE /plan/restore/image/{plan_id}/ — supprimer

  • GET /plan/restore/image/{plan_id}/execute/ — exécuter (réponse 202)

  • GET /plan/restore/image/{plan_id}/history/ — historique (Page_RestorePlanRun_)

3. Plans de restauration Fichiers #

  • GET /plan/restore/file/ — lister (Page_FileRestorePlan_)

  • POST /plan/restore/file/ — créer (FileRestorePlanCreate)

  • GET /plan/restore/file/{plan_id}/ — lire (FileRestorePlan)

  • PUT /plan/restore/file/{plan_id}/ — mettre à jour (FileRestorePlanUpdate)

  • DELETE /plan/restore/file/{plan_id}/ — supprimer

  • GET /plan/restore/file/{plan_id}/execute/ — exécuter (réponse 202)

  • GET /plan/restore/file/{plan_id}/history/ — historique (Page_RestorePlanRun_)

4. Assignation de schedules & agents à un plan (restore) #

Même logique que pour les backups, mais pour les plans de restore.

Schedules #

  • POST /plan/restore/{plan_id}/assign-schedule/{schedule_id}/

  • POST /plan/restore/{plan_id}/remove-schedule/{schedule_id}/

Agents #

  • POST /plan/restore/{plan_id}/assign-agent/{agent_id}/

  • POST /plan/restore/{plan_id}/remove-agent/{agent_id}/

Tous retournent 204 si succès.

Domaine Schedules de plan (plans-schedule) #

Gestion des plannings (cron) réutilisables pour plusieurs plans.

Lister les schedules #

  • GET /plan/schedule/schedule/

    • Filtres :

      • id (uuid)

      • enabled (bool)

    • Réponse : Page_Scheduling_.

Créer un schedule #

  • POST /plan/schedule/schedule/

    • Body : CreateScheduling

      • cron_calendar (CronCalendar) :

        • minute, hour, day_of_month, month_of_year, day_of_week?

        • timezone (défaut UTC)

      • enabled (bool, défaut false)

    • Réponse : Scheduling.

Modifier / supprimer un schedule #

  • PUT /plan/schedule/schedule/{schedule_id}/

    • Body : UpdateScheduling

    • Réponse : 204

  • DELETE /plan/schedule/schedule/{schedule_id}/

    • Réponse : 204

Domaine Agents (agents) #

Gère les agents installés sur les machines (clients Cybee) et leur approbation.

1. Agents enregistrés #

Lister les agents #

  • GET /agent/

    • But : liste des agents connus et enregistrés.

    • Filtres (plusieurs valeurs possibles par champ, combinées par OR) :

      • id (array[uuid])

      • machine_id (array[NonEmptyStr])

      • custom_name (array[NonEmptyStr])

      • host_name (array[NonEmptyStr])

      • online (bool)

    • Réponse : Page_AgentInfo_

      • Items de type AgentInfo (id, machine_id, host_name, custom_name, online, approved_at, last_seen, timestamps).

Mettre à jour / supprimer un agent #

  • PUT /agent/{agent_id}/

    • Body : AgentUpdate (par ex. custom_name)

    • Réponse : 200 (corps peu ou pas documenté).

  • DELETE /agent/{agent_id}/

    • Réponse : 200.

Approuver un agent #

  • POST /agent/{agent_id}/approve/

    • But : marquer un agent comme approuvé pour utilisation.

    • Réponse : 204.

2. Agents non enregistrés #

Lister les agents non enregistrés #

  • GET /agent/unregistered/

    • But : lister les agents vus par le système mais non encore enregistrés / approuvés.

    • Pagination standard : page, per_page, order_by.

    • Réponse : Page_UnregisteredAgentInfo_.

Domaine CMDB (cmdb) #

Le CMDB centralise les informations machines remontées par les agents (matériel, OS, réseau, etc.) ainsi que leur historique.

1. Vue courante des machines #

Lister les machines CMDB #

  • GET /cmdb/machines/

    • But : liste des machines et de leurs infos actuelles.

    • Filtres :

      • machine_id (NonEmptyStr)

    • Réponse : Page_Machine_

    • Champs temporels pour chaque machine :

      • created_at : date d’apparition dans le système

      • changed_at : dernière modification de l’info machine

      • updated_at : dernier contact avec la machine

2. Historique des machines #

Lister l’historique CMDB #

  • GET /cmdb/machines/historical/

    • But : liste historique des états de machines.

    • Filtres :

      • machine_id (NonEmptyStr)

    • Réponse : Page_HistoricalMachine_

    • Interprétation des dates :

      • started_at : première fois où ce snapshot a été observé

      • updated_at : dernière fois où ce snapshot est encore valide
        → Quand la machine change, un nouveau snapshot est créé, l’ancien n’est plus mis à jour.