SERVORdocs
en

API Serveurs

Lisez vos serveurs via l'API Servor avec un jeton servers:read — listez les serveurs de votre équipe et récupérez le détail d'un serveur.

Lisez les serveurs de votre équipe via l'API. Ces endpoints servent à construire un inventaire, alimenter vos propres tableaux de bord ou retrouver l'id d'un serveur avant d'en lire l'historique de commandes. Tout est en lecture seule : l'ajout et la modification des serveurs restent dans le tableau de bord : ajouter un serveur dans Servor.

Ces endpoints requièrent le scope servers:read.

get/v1/serversScope: servers:read

List servers

Exemple de requête

curl https://api.servor.app/v1/servers \
  -H "Authorization: Bearer sv_live_..."

Exemple de réponse

[
  {
    "id": "uuid",
    "name": "web-01",
    "host": "203.0.113.10",
    "os": "debian",
    "tags": [
      "prod"
    ],
    "lastSeenAt": "2026-08-20T10:00:00.000Z",
    "createdAt": "2026-08-01T00:00:00.000Z"
  }
]
get/v1/servers/{id}Scope: servers:read

Get a server

Paramètres

  • iduuidpath · requis

    The server id.

Exemple de requête

curl https://api.servor.app/v1/servers/:id \
  -H "Authorization: Bearer sv_live_..."

Exemple de réponse

{
  "id": "uuid",
  "name": "web-01",
  "host": "203.0.113.10",
  "os": "debian",
  "tags": [
    "prod"
  ],
  "lastSeenAt": "2026-08-20T10:00:00.000Z",
  "createdAt": "2026-08-01T00:00:00.000Z"
}
get/v1/server-groupsScope: servers:read

List server groups

Exemple de requête

curl https://api.servor.app/v1/server-groups \
  -H "Authorization: Bearer sv_live_..."

Exemple de réponse

[
  {
    "id": "uuid",
    "name": "production",
    "color": "emerald",
    "position": 1024
  }
]
get/v1/servers/{id}/metricsScope: metrics:read

Read a server metric series

Paramètres

  • idstringpath · requis

    Server id.

  • rangestringquery · optionnel

    One of 1h, 24h, 7d, 30d (default 24h). Past 24h the series is served from hourly rollups.

Exemple de requête

curl https://api.servor.app/v1/servers/:id/metrics \
  -H "Authorization: Bearer sv_live_..."

Exemple de réponse

{
  "resolution": "raw",
  "range": "24h",
  "points": [
    {
      "at": "2026-08-20T10:00:00.000Z",
      "cpuPercent": 12.4,
      "ramUsedMb": 2048,
      "ramTotalMb": 8192,
      "diskUsedGb": 31,
      "diskTotalGb": 80
    }
  ]
}
get/v1/servers/{id}/scheduled-commandsScope: scheduled-commands:read

List scheduled commands for a server

Paramètres

  • idstringpath · requis

    Server id.

Exemple de requête

curl https://api.servor.app/v1/servers/:id/scheduled-commands \
  -H "Authorization: Bearer sv_live_..."

Exemple de réponse

[
  {
    "id": "uuid",
    "name": "Nightly backup",
    "command": "systemctl start backup",
    "cron": "0 3 * * *",
    "enabled": true,
    "lastRunAt": "2026-08-20T03:00:00.000Z",
    "lastExitCode": 0,
    "consecutiveFailures": 0
  }
]

Ce que vous récupérez

  • GET /v1/servers — la liste des serveurs de votre équipe.
  • GET /v1/servers/{id} — le détail d'un serveur.

Exemple

curl https://api.servor.app/v1/servers \
  -H "Authorization: Bearer sv_live_..."

Reprenez un id de cette liste pour lire un serveur :

curl https://api.servor.app/v1/servers/srv_123 \
  -H "Authorization: Bearer sv_live_..."

Sections de parc

GET /v1/server-groups renvoie les sections dans lesquelles le parc est rangé, dans l'ordre de l'équipe. Chaque serveur porte le groupId correspondant.

Couvert par servers:read plutôt que par un scope à lui : une section fait partie de la forme du parc, et un jeton qui listerait les machines sans les titres sous lesquels elles se rangent renverrait un inventaire que personne ne peut classer.

Métriques d'un serveur

GET /v1/servers/{id}/metrics renvoie les séries CPU, RAM et disque, pour les retracer dans l'outil qui dessine déjà vos courbes. Scope metrics:read.

curl "https://api.servor.app/v1/servers/$ID/metrics?range=24h" \
  -H "Authorization: Bearer sv_live_..."

range vaut 1h, 24h, 7d ou 30d (défaut 24h). Au-delà de 24 h la série est servie depuis les agrégats horaires : le champ resolution indique lequel des deux vous lisez.

Commandes planifiées d'un serveur

GET /v1/servers/{id}/scheduled-commands renvoie le planning cron de chaque tâche et son dernier résultat — de quoi répondre à « la sauvegarde de cette nuit a-t-elle tourné ? ». Scope scheduled-commands:read.

Lire un planning ne permet pas de le déclencher

Le texte de la commande est renvoyé — un planning qu'on ne peut pas lire n'est pas un planning qu'on peut auditer — et cela n'accorde rien pour autant : aucun jeton ne peut exécuter quoi que ce soit. Une exécution doit être signée dans un navigateur avec la clé de votre coffre, que l'API ne détient jamais.

Remarques

  • Les réponses n'incluent jamais d'identifiants SSH ni de données chiffrées.
  • Pour lire l'historique de commandes d'un serveur, voir l'API Commandes.
  • Un 403 signifie que votre jeton n'a pas le scope servers:read ; un 404 signifie que l'id du serveur n'existe pas ou n'appartient pas à votre équipe. Voir les erreurs.

Voir aussi

API Historique de commandesLisez ce qui a été exécuté sur un serveur.API MoniteursLisez vos moniteurs et leurs vérifications.Ajouter un serveurInstallez l'agent depuis le tableau de bord.ErreursRéponses d'erreur typées et codes de statut.
PrécédentErreursSuivantMoniteurs