Perimetry Cloud
ENDECommencer gratuitement
Produit
Ressources
Tarifs
EnglishDeutschSe connecterCommencer gratuitement

L’API et les clés d’API

Créer une clé en lecture seule ou d’audit, puis lire domaines, constats et comparaisons, lancer des audits et les suivre : la référence de l’API, avec des exemples curl.

Mis à jour le

À partir de l’offre Solo, une API permet à vos scripts, à votre intégration continue et à vos assistants d’IA de lire les résultats de vos domaines et de lancer des audits. Elle répond en JSON, et le dernier audit peut aussi être lu en SARIF, le format que comprennent les outils d’analyse de code. L’action GitHub et le serveur MCP reposent sur elle.

Créer une clé

  1. Ouvrez Réglages et trouvez la carte Clés d’API.
  2. Donnez à la clé un nom qui dit où elle sert, comme « GitHub Actions ».
  3. Cochez Peut lancer des audits seulement si cette clé doit lancer des audits (une tâche d’intégration continue qui en lance un à chaque déploiement). Laissez la case vide pour une clé qui ne fait que lire.
  4. Appuyez sur Créer la clé et copiez-la tout de suite : elle commence par pc_ et n’est affichée qu’une fois. Gardez-la comme secret dans votre intégration continue ou votre gestionnaire de mots de passe.

Seuls les propriétaires et les administrateurs peuvent créer et révoquer des clés. La carte liste chaque clé avec ses premiers caractères, ce qu’elle peut faire, sa date de création et sa dernière utilisation. Révoquer arrête une clé aussitôt. Quand un membre est retiré de l’espace, les clés qu’il a créées sont révoquées avec lui.

Appeler l’API

L’API se trouve à https://app.perimetry.cloud. Envoyez la clé dans l’en-tête Authorization de chaque requête, jamais dans l’adresse :

Authorization: Bearer pc_…

Chaque réponse porte Perimetry-Api-Version: 1 et l’état de votre limite horaire (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset). La version 1 ne fait que gagner des champs : rien n’est renommé ni retiré, si bien qu’un script écrit aujourd’hui continue de fonctionner.

Partout où une requête prend :id, vous pouvez donner l’identifiant du domaine ou son nom (example.com).

Les requêtes du domaine, des constats et de la comparaison acceptent lang=fr ou lang=de pour les titres, explications et corrections des constats en français ou en allemand ; l’anglais par défaut.

Requête Ce qu’elle fait
GET /api/v1/me L’espace, l’offre, ce que la clé peut faire, et ce qui reste de la limite horaire.
GET /api/v1/domains Les domaines de l’espace : identifiant, nom, état, client, note, lettre, constats ouverts par gravité, dates du dernier et du prochain audit, lien vers le rapport. ?name=example.com n’en garde qu’un.
GET /api/v1/domains/:id Un domaine : sa note, son dernier audit avec l’évolution de la note depuis le précédent, les constats nouveaux et corrigés, et les trois constats à corriger en premier.
GET /api/v1/domains/:id/findings Les constats ouverts du dernier audit, du plus grave au moins grave, chacun avec sa correction, les enregistrements DNS prêts à copier et les exigences NIS2, Cyber Essentials et ISO 27001. Options : min_severity, include_accepted=1, limit, lang.
GET /api/v1/domains/:id/compare Ce qui a changé depuis l’audit précédent : note avant et après, constats ajoutés, corrigés ou changés de gravité, hôtes, ports, certificats, sosies.
GET /api/v1/domains/:id/audits L’historique des audits : date, note, lettre, comptes (limit, 100 au plus).
GET /api/v1/domains/:id/latest Le dernier audit en entier, avec ses constats et ceux qui sont acceptés ; ?format=sarif pour le SARIF.
POST /api/v1/domains/:id/audit Lance un audit d’un domaine prouvé (clé qui peut lancer des audits). Répond 202 avec une exécution à suivre.
GET /api/v1/runs/:id Où en est cet audit : queued (en file), running (en cours, avec sa progression), done (nouvelle note, note précédente, évolution) ou failed (échoué).

Chaque champ de chaque réponse, les codes d’erreur et la spécification OpenAPI 3.1 à télécharger (pour Postman, les générateurs de code et les outils d’automatisation) se trouvent dans la référence de l’API.

Exemples

Lister vos domaines :

curl -H "Authorization: Bearer $PERIMETRY_API_KEY" https://app.perimetry.cloud/api/v1/domains

Les constats graves d’un domaine, avec leurs corrections, en français :

curl -H "Authorization: Bearer $PERIMETRY_API_KEY" \
  "https://app.perimetry.cloud/api/v1/domains/example.com/findings?min_severity=high&lang=fr"

Ce qui a changé depuis l’audit précédent :

curl -H "Authorization: Bearer $PERIMETRY_API_KEY" https://app.perimetry.cloud/api/v1/domains/example.com/compare

Lancer un audit, puis le suivre jusqu’à la fin :

curl -X POST -H "Authorization: Bearer $PERIMETRY_API_KEY" https://app.perimetry.cloud/api/v1/domains/example.com/audit
# → {"apiVersion":1,"queued":true,"run":{"id":"6f1c…","status":"queued",…}}
curl -H "Authorization: Bearer $PERIMETRY_API_KEY" https://app.perimetry.cloud/api/v1/runs/6f1c…

Le dernier audit en SARIF, pour un outil d’analyse de code :

curl -H "Authorization: Bearer $PERIMETRY_API_KEY" -o perimetry.sarif \
  "https://app.perimetry.cloud/api/v1/domains/example.com/latest?format=sarif"

Limites

  • Appels par heure, pour tout l’espace : 300 avec Solo, 1 200 avec Agency, 3 600 avec Agency Plus. Au-delà, l’API répond 429 avec un en-tête Retry-After jusqu’au début de l’heure suivante.
  • Audits à la demande : la même règle que le bouton Auditer maintenant (un par heure et par domaine avec Solo, aussi souvent que nécessaire avec les offres Agency), et, par l’API, un toutes les 15 minutes par domaine. Tant qu’un audit du domaine attend ou tourne déjà, une nouvelle demande suit celui-là au lieu d’en lancer un autre.

Erreurs

Les erreurs répondent en JSON avec un message et un code stable : {"error": "…", "code": "…"}.

  • 400 invalid_parameter : un paramètre a une valeur que l’API n’accepte pas, par exemple min_severity=urgent ; le message indique les valeurs possibles.
  • 401 unauthorized : la clé est absente, mal formée, révoquée ou inconnue.
  • 403 plan_excludes_api : l’offre de l’espace ne comprend pas l’API. insufficient_scope : la clé ne peut pas lancer d’audit.
  • 404 not_found : le domaine n’est pas dans cet espace ; no_audit : il n’a pas encore d’audit.
  • 409 not_verified : un audit a été demandé pour un domaine qui n’est pas prouvé.
  • 429 rate_limited : la limite horaire est atteinte ; audit_too_soon : un audit à la demande de ce domaine a tourné trop récemment ; too_many_failures : soixante requêtes avec une mauvaise clé sont venues de votre réseau en quinze minutes. Dans chaque cas, Retry-After donne le nombre de secondes à attendre.

Le journal

Chaque appel est enregistré pendant 90 jours : son heure, sa clé, la route (jamais les paramètres) et la réponse. Les propriétaires et les administrateurs voient les derniers sous Derniers appels de l’API dans la carte des clés. Chaque audit lancé par l’API apparaît aussi dans l’Activité de l’espace, avec la clé qui l’a lancé.

Idées