Référence de l’API

GET /api/v1/me

La clé, son espace et sa limite horaire

L’espace et l’offre de la clé, ce qu’elle peut faire (ses droits) et ce qui reste de la limite horaire. Un bon premier appel pour vérifier une clé.

Exemple

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

Réponse 200

{
  "apiVersion": 1,
  "workspace": {
    "name": "Acme",
    "plan": "agency"
  },
  "key": {
    "name": "GitHub Actions",
    "prefix": "pc_3kQx",
    "scopes": [
      "read",
      "audit"
    ]
  },
  "rateLimit": {
    "limit": 1200,
    "remaining": 1187,
    "resetAt": "2026-11-12T10:00:00.000Z"
  }
}

Erreurs

• 401 La clé manque, est mal formée, révoquée ou inconnue (code unauthorized).
• 403 L’offre de l’espace ne comprend pas l’API (code plan_excludes_api). X-RateLimit-Limit et X-RateLimit-Remaining valent 0.
• 429 La limite horaire est atteinte (rate_limited), ou trop de requêtes sont venues avec une mauvaise clé (too_many_failures). Attendez Retry-After secondes.
• 500 Un problème de notre côté (code internal).

GET /api/v1/domains

Lister les domaines

Chaque domaine de l’espace avec son état, son client, sa note, ses constats ouverts par gravité, les dates du dernier et du prochain audit et un lien vers sa page.

Paramètres

Exemple

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

Réponse 200

{
  "apiVersion": 1,
  "domains": [
    {
      "id": "3f9c2a64-5b1e-4c0a-9a57-2f6d8e1b4c10",
      "name": "example.com",
      "status": "verified",
      "verified": true,
      "client": null,
      "score": 72,
      "grade": "C",
      "counts": {
        "critical": 0,
        "high": 2,
        "medium": 3,
        "low": 4,
        "info": 6
      },
      "lastAuditAt": "2026-11-12T03:14:07.000Z",
      "nextAuditAt": "2026-11-19T03:14:07.000Z",
      "attention": true,
      "links": {
        "app": "https://app.perimetry.cloud/domains/3f9c2a64-5b1e-4c0a-9a57-2f6d8e1b4c10",
        "api": "/api/v1/domains/3f9c2a64-5b1e-4c0a-9a57-2f6d8e1b4c10"
      }
    }
  ]
}

Erreurs

• 401 La clé manque, est mal formée, révoquée ou inconnue (code unauthorized).
• 403 L’offre de l’espace ne comprend pas l’API (code plan_excludes_api). X-RateLimit-Limit et X-RateLimit-Remaining valent 0.
• 429 La limite horaire est atteinte (rate_limited), ou trop de requêtes sont venues avec une mauvaise clé (too_many_failures). Attendez Retry-After secondes.
• 500 Un problème de notre côté (code internal).

GET /api/v1/domains/{id}

Un domaine et son dernier audit

Le domaine, son dernier audit avec l’évolution de la note depuis le précédent, le nombre de constats nouveaux et corrigés, et les trois constats à corriger en premier.

Paramètres

Exemple

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

Réponse 200

{
  "apiVersion": 1,
  "domain": {
    "id": "3f9c2a64-5b1e-4c0a-9a57-2f6d8e1b4c10",
    "name": "example.com",
    "status": "verified",
    "verified": true,
    "client": null,
    "score": 72,
    "grade": "C",
    "counts": {
      "critical": 0,
      "high": 2,
      "medium": 3,
      "low": 4,
      "info": 6
    },
    "lastAuditAt": "2026-11-12T03:14:07.000Z",
    "nextAuditAt": "2026-11-19T03:14:07.000Z",
    "attention": true,
    "links": {
      "app": "https://app.perimetry.cloud/domains/3f9c2a64-5b1e-4c0a-9a57-2f6d8e1b4c10",
      "api": "/api/v1/domains/3f9c2a64-5b1e-4c0a-9a57-2f6d8e1b4c10"
    }
  },
  "lastAudit": {
    "id": "8b1d5e2f-7c3a-4f6e-b2d9-0a4c6e8f1a23",
    "startedAt": "2026-11-12T03:14:07.000Z",
    "finishedAt": "2026-11-12T03:16:52.000Z",
    "trigger": "schedule",
    "scannerVersion": "0.13.1",
    "score": 72,
    "grade": "C",
    "counts": {
      "critical": 0,
      "high": 2,
      "medium": 3,
      "low": 4,
      "info": 6
    },
    "attention": true,
    "previous": {
      "id": "c4e7a1b9-2d5f-4a8c-9e3b-6f1a2d4c8e57",
      "startedAt": "2026-11-05T03:14:07.000Z",
      "score": 80,
      "grade": "B"
    },
    "scoreDelta": -8,
    "newFindings": 2,
    "fixedFindings": 1
  },
  "doFirst": [
    {
      "fp": "5d0e3b7c1a9f4e26",
      "id": "email.dmarc.p_none",
      "severity": "high",
      "title": "DMARC policy only monitors (p=none)",
      "target": "example.com"
    }
  ]
}

Erreurs

• 401 La clé manque, est mal formée, révoquée ou inconnue (code unauthorized).
• 403 L’offre de l’espace ne comprend pas l’API (code plan_excludes_api). X-RateLimit-Limit et X-RateLimit-Remaining valent 0.
• 404 Absent de cet espace (code not_found).
• 429 La limite horaire est atteinte (rate_limited), ou trop de requêtes sont venues avec une mauvaise clé (too_many_failures). Attendez Retry-After secondes.
• 500 Un problème de notre côté (code internal).

GET /api/v1/domains/{id}/findings

Constats ouverts du dernier audit

Les constats ouverts du dernier audit, du plus grave au plus léger, chacun avec sa correction, les enregistrements DNS prêts à copier et les exigences de conformité qu’il concerne. Les constats acceptés sur demande.

Paramètres

Exemple

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

Réponse 200

{
  "apiVersion": 1,
  "domain": {
    "id": "3f9c2a64-5b1e-4c0a-9a57-2f6d8e1b4c10",
    "name": "example.com"
  },
  "audit": {
    "id": "8b1d5e2f-7c3a-4f6e-b2d9-0a4c6e8f1a23",
    "startedAt": "2026-11-12T03:14:07.000Z",
    "score": 72,
    "grade": "C",
    "counts": {
      "critical": 0,
      "high": 2,
      "medium": 3,
      "low": 4,
      "info": 6
    }
  },
  "total": 1,
  "findings": [
    {
      "fp": "5d0e3b7c1a9f4e26",
      "id": "email.dmarc.p_none",
      "severity": "high",
      "category": "email",
      "target": "example.com",
      "title": "DMARC policy only monitors (p=none)",
      "detail": "Receivers are told to deliver mail that fails DMARC anyway: anyone can still send mail in the domain’s name.",
      "evidence": "v=DMARC1; p=none; rua=mailto:dmarc@example.com",
      "fix": "Move the policy to quarantine, then reject, once the reports show every sender is aligned.",
      "references": [
        "https://www.rfc-editor.org/rfc/rfc7489"
      ],
      "records": [
        {
          "type": "TXT",
          "name": "_dmarc.example.com",
          "value": "v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com",
          "replaces": "v=DMARC1; p=none; rua=mailto:dmarc@example.com",
          "note": "One step stricter: mail that fails DMARC goes to spam."
        }
      ],
      "compliance": [
        "NIS2 Art. 21(2)(j)",
        "ISO 27001 A.8.21"
      ]
    }
  ]
}

Erreurs

• 400 Un paramètre a une valeur que l’API n’accepte pas (code invalid_parameter) ; le message nomme le paramètre et les valeurs possibles.
• 401 La clé manque, est mal formée, révoquée ou inconnue (code unauthorized).
• 403 L’offre de l’espace ne comprend pas l’API (code plan_excludes_api). X-RateLimit-Limit et X-RateLimit-Remaining valent 0.
• 404 Absent de cet espace (not_found), ou le domaine n’a pas encore d’audit (no_audit).
• 429 La limite horaire est atteinte (rate_limited), ou trop de requêtes sont venues avec une mauvaise clé (too_many_failures). Attendez Retry-After secondes.
• 500 Un problème de notre côté (code internal).

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é, et les changements de l’infrastructure : hôtes, ports, certificats, domaines sosies, services cloud.

Paramètres

Exemple

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

Réponse 200

{
  "apiVersion": 1,
  "domain": {
    "id": "3f9c2a64-5b1e-4c0a-9a57-2f6d8e1b4c10",
    "name": "example.com"
  },
  "audit": {
    "id": "8b1d5e2f-7c3a-4f6e-b2d9-0a4c6e8f1a23",
    "startedAt": "2026-11-12T03:14:07.000Z",
    "score": 72,
    "grade": "C"
  },
  "previous": {
    "id": "c4e7a1b9-2d5f-4a8c-9e3b-6f1a2d4c8e57",
    "startedAt": "2026-11-05T03:14:07.000Z",
    "score": 80,
    "grade": "B"
  },
  "comparison": {
    "score": {
      "from": 80,
      "to": 72,
      "delta": -8
    },
    "attention": true,
    "worstAdded": "high",
    "added": [
      {
        "fp": "5d0e3b7c1a9f4e26",
        "id": "email.dmarc.p_none",
        "severity": "high",
        "title": "DMARC policy only monitors (p=none)",
        "target": "example.com"
      }
    ],
    "resolved": [],
    "severityChanged": [],
    "infra": {
      "newHosts": [
        "staging.example.com"
      ],
      "goneHosts": [],
      "newLookalikes": [],
      "newCloud": [],
      "ports": [
        {
          "ip": "192.0.2.10",
          "opened": [
            8080
          ],
          "closed": []
        }
      ],
      "certificates": [],
      "newCertificates": [
        {
          "issuer": "Let's Encrypt",
          "names": [
            "staging.example.com"
          ],
          "notBefore": "2026-11-10T00:00:00.000Z"
        }
      ]
    }
  }
}

Erreurs

• 401 La clé manque, est mal formée, révoquée ou inconnue (code unauthorized).
• 403 L’offre de l’espace ne comprend pas l’API (code plan_excludes_api). X-RateLimit-Limit et X-RateLimit-Remaining valent 0.
• 404 Absent de cet espace (not_found), ou le domaine n’a pas encore d’audit (no_audit).
• 429 La limite horaire est atteinte (rate_limited), ou trop de requêtes sont venues avec une mauvaise clé (too_many_failures). Attendez Retry-After secondes.
• 500 Un problème de notre côté (code internal).

GET /api/v1/domains/{id}/audits

Historique des audits

Les audits du domaine, du plus récent au plus ancien : date, déclenchement, note, constats par gravité.

Paramètres

Exemple

curl -H "Authorization: Bearer $PERIMETRY_API_KEY" \
  "https://app.perimetry.cloud/api/v1/domains/example.com/audits?limit=10"

Réponse 200

{
  "apiVersion": 1,
  "domain": {
    "id": "3f9c2a64-5b1e-4c0a-9a57-2f6d8e1b4c10",
    "name": "example.com"
  },
  "audits": [
    {
      "id": "8b1d5e2f-7c3a-4f6e-b2d9-0a4c6e8f1a23",
      "startedAt": "2026-11-12T03:14:07.000Z",
      "trigger": "schedule",
      "score": 72,
      "grade": "C",
      "counts": {
        "high": 2,
        "medium": 3,
        "low": 4,
        "info": 6
      },
      "attention": true
    }
  ]
}

Erreurs

• 401 La clé manque, est mal formée, révoquée ou inconnue (code unauthorized).
• 403 L’offre de l’espace ne comprend pas l’API (code plan_excludes_api). X-RateLimit-Limit et X-RateLimit-Remaining valent 0.
• 404 Absent de cet espace (code not_found).
• 429 La limite horaire est atteinte (rate_limited), ou trop de requêtes sont venues avec une mauvaise clé (too_many_failures). Attendez Retry-After secondes.
• 500 Un problème de notre côté (code internal).

GET /api/v1/domains/{id}/latest

Le dernier audit complet, ou en SARIF

Le dernier audit tel qu’il est enregistré, avec ses constats et les constats acceptés, en anglais ; ou, avec format=sarif, un document SARIF 2.1.0 pour les outils d’analyse de code (servi en application/json).

Paramètres

Exemple

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

Réponse 200

L’audit (JSON), ou du SARIF (application/sarif+json) avec format=sarif.

{
  "apiVersion": 1,
  "domain": "example.com",
  "audit": {
    "id": "8b1d5e2f-7c3a-4f6e-b2d9-0a4c6e8f1a23",
    "domain_id": "3f9c2a64-5b1e-4c0a-9a57-2f6d8e1b4c10",
    "started_at": "2026-11-12T03:14:07.000Z",
    "finished_at": "2026-11-12T03:16:52.000Z",
    "duration_ms": 165000,
    "scanner_version": "0.13.1",
    "score": 72,
    "grade": "C",
    "counts": {
      "high": 2,
      "medium": 3,
      "low": 4,
      "info": 6
    },
    "snapshot": {},
    "errors": [],
    "diff": null,
    "attention": true,
    "trigger": "schedule",
    "created_at": "2026-11-12T03:16:52.000Z"
  },
  "findings": [
    {
      "fp": "5d0e3b7c1a9f4e26",
      "id": "email.dmarc.p_none",
      "severity": "high",
      "category": "email",
      "target": "example.com",
      "title": "DMARC policy only monitors (p=none)",
      "fix": "Move the policy to quarantine, then reject."
    }
  ],
  "accepted": []
}

Erreurs

• 401 La clé manque, est mal formée, révoquée ou inconnue (code unauthorized).
• 403 L’offre de l’espace ne comprend pas l’API (code plan_excludes_api). X-RateLimit-Limit et X-RateLimit-Remaining valent 0.
• 404 Absent de cet espace (not_found), ou le domaine n’a pas encore d’audit (no_audit).
• 429 La limite horaire est atteinte (rate_limited), ou trop de requêtes sont venues avec une mauvaise clé (too_many_failures). Attendez Retry-After secondes.
• 500 Un problème de notre côté (code internal).

POST /api/v1/domains/{id}/audit

Lancer un audit

Lance un audit d’un domaine prouvé ; la clé doit avoir le droit audit. Répond 202 avec une exécution à suivre à /api/v1/runs/{id}. Si un audit du domaine attend déjà ou tourne, la nouvelle exécution suit celui-là (alreadyQueued). Même limite que le bouton Auditer maintenant (un par heure et par domaine avec Solo) et, par l’API, un toutes les 15 minutes par domaine. Pas de corps de requête.

Paramètres

Exemple

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

Réponse 202

Accepté : l’audit est en file d’attente (ou l’était déjà).

{
  "apiVersion": 1,
  "queued": true,
  "alreadyQueued": false,
  "run": {
    "id": "6f1c9d2e-4b7a-4c3e-8f5d-1a2b3c4d5e6f",
    "status": "queued",
    "domain": {
      "id": "3f9c2a64-5b1e-4c0a-9a57-2f6d8e1b4c10",
      "name": "example.com"
    },
    "requestedAt": "2026-11-12T09:00:02.000Z",
    "progress": null,
    "audit": null,
    "previous": {
      "id": "c4e7a1b9-2d5f-4a8c-9e3b-6f1a2d4c8e57",
      "startedAt": "2026-11-05T03:14:07.000Z",
      "score": 72,
      "grade": "C"
    },
    "scoreDelta": null,
    "links": {
      "self": "/api/v1/runs/6f1c9d2e-4b7a-4c3e-8f5d-1a2b3c4d5e6f",
      "app": "https://app.perimetry.cloud/domains/3f9c2a64-5b1e-4c0a-9a57-2f6d8e1b4c10"
    }
  }
}

Erreurs

• 401 La clé manque, est mal formée, révoquée ou inconnue (code unauthorized).
• 403 L’offre ne comprend pas l’API (plan_excludes_api), ou la clé ne peut pas lancer d’audit (insufficient_scope).
• 404 Absent de cet espace (code not_found).
• 409 Le domaine n’est pas prouvé (code not_verified).
• 429 La limite horaire est atteinte (rate_limited), trop de requêtes sont venues avec une mauvaise clé (too_many_failures), ou un audit à la demande de ce domaine a eu lieu trop récemment (audit_too_soon). Attendez Retry-After secondes.
• 500 Un problème de notre côté (code internal).
• 503 L’audit n’a pas pu être mis en file ; réessayez (code unavailable).
• 507 L’espace a utilisé le stockage de son offre (storage_quota), ou notre stockage est plein pour le moment (storage_full) : pas d’audit à la demande tant qu’il n’y a pas de place. Supprimez d’anciennes données ou passez à une offre plus grande. Tout ce qui est enregistré reste lisible.

GET /api/v1/runs/{id}

Où en est un audit lancé par l’API

queued (en attente), running (en cours, avec sa progression), done (terminé : nouvelle note, note précédente, évolution) ou failed (échoué). Interrogez toutes les 10 à 30 secondes ; un audit prend en général quelques minutes.

Paramètres

Exemple

curl -H "Authorization: Bearer $PERIMETRY_API_KEY" \
  "https://app.perimetry.cloud/api/v1/runs/6f1c9d2e-4b7a-4c3e-8f5d-1a2b3c4d5e6f"

Réponse 200

{
  "apiVersion": 1,
  "run": {
    "id": "6f1c9d2e-4b7a-4c3e-8f5d-1a2b3c4d5e6f",
    "status": "done",
    "domain": {
      "id": "3f9c2a64-5b1e-4c0a-9a57-2f6d8e1b4c10",
      "name": "example.com"
    },
    "requestedAt": "2026-11-12T09:00:02.000Z",
    "progress": null,
    "audit": {
      "id": "8b1d5e2f-7c3a-4f6e-b2d9-0a4c6e8f1a23",
      "startedAt": "2026-11-12T09:00:05.000Z",
      "finishedAt": "2026-11-12T09:02:41.000Z",
      "trigger": "manual",
      "score": 78,
      "grade": "C",
      "counts": {
        "critical": 0,
        "high": 1,
        "medium": 3,
        "low": 4,
        "info": 6
      },
      "newFindings": 0,
      "fixedFindings": 1,
      "worstAdded": null
    },
    "previous": {
      "id": "c4e7a1b9-2d5f-4a8c-9e3b-6f1a2d4c8e57",
      "startedAt": "2026-11-05T03:14:07.000Z",
      "score": 72,
      "grade": "C"
    },
    "scoreDelta": 6,
    "links": {
      "self": "/api/v1/runs/6f1c9d2e-4b7a-4c3e-8f5d-1a2b3c4d5e6f",
      "app": "https://app.perimetry.cloud/domains/3f9c2a64-5b1e-4c0a-9a57-2f6d8e1b4c10"
    }
  }
}

Erreurs

• 401 La clé manque, est mal formée, révoquée ou inconnue (code unauthorized).
• 403 L’offre de l’espace ne comprend pas l’API (code plan_excludes_api). X-RateLimit-Limit et X-RateLimit-Remaining valent 0.
• 404 Absent de cet espace (code not_found).
• 429 La limite horaire est atteinte (rate_limited), ou trop de requêtes sont venues avec une mauvaise clé (too_many_failures). Attendez Retry-After secondes.
• 500 Un problème de notre côté (code internal).

GET /api/v1/openapi.json

Cette spécification

La description OpenAPI 3.1 de l’API. Publique : sans clé, non décomptée de la limite horaire.

Sans clé.

Exemple

curl \
  "https://app.perimetry.cloud/api/v1/openapi.json"

Réponse 200

Le document OpenAPI.