POST /api/v1/check
La référence complète de la vérification à la demande : le corps, chaque champ de la réponse, les codes HTTP, et des exemples curl, JavaScript et GitHub Actions.
Mis à jour le 11 septembre 2026
Sur cette page
POST https://postship.fr/api/v1/check vérifie une URL publique maintenant, avec le même moteur que le cycle et le scan public, et rend le résultat dans la réponse, en synchrone. Une CI qui devrait interroger une file d'attente attendrait plus longtemps qu'elle ne met à vérifier, et chaque sondage serait une occasion de plus de se tromper. Comptez jusqu'à 60 secondes.
La requête
| Méthode | POST |
| En-têtes | Authorization: Bearer psk_… et Content-Type: application/json |
| Corps | {"url": "https://votre-site.fr/page"} — une seule clé, url, en https |
L'URL doit être en https, sans identifiants (https://user:pass@… est refusé), et mener vers un hôte public : la même garde que pour toute URL surveillée, parce qu'un jeton valide n'autorise pas à faire pointer notre sonde sur un réseau privé. Une URL refusée ne consomme pas de quota : elle est contrôlée avant la réservation.
export POSTSHIP_TOKEN=psk_…
curl -sS -X POST https://postship.fr/api/v1/check \
-H "Authorization: Bearer $POSTSHIP_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url":"https://votre-site.fr"}'La réponse
200 avec un objet JSON :
{
"url": "https://votre-site.fr/",
"score": 75,
"reason": "−25 asset manquant",
"outcome": "fail",
"failed": 1,
"checks": [
{ "kind": "http", "label": "Page et ressources", "outcome": "fail", "detail": "2 ressource(s) déclarée(s) mais absente(s)" },
{ "kind": "index", "label": "Indexabilité", "outcome": "pass", "detail": "Crawlable, canonical cohérent" },
{ "kind": "og", "label": "Carte sociale", "outcome": "pass", "detail": "Titre et image valides" },
{ "kind": "sitemap", "label": "Sitemap", "outcome": "skip", "detail": "Aucun sitemap déclaré" },
{ "kind": "ssl", "label": "Certificat SSL", "outcome": "pass", "detail": "61 jours avant expiration" },
{ "kind": "ia", "label": "Visibilité IA", "outcome": "pass", "detail": "Lisible et citable par les moteurs de réponse" }
],
"quota": { "used": 12, "limit": 300, "remaining": 288 }
}| Champ | Type | Ce qu'il contient |
|---|---|---|
url | string | L'URL vérifiée, normalisée |
score | number | Le Ship Score, de 0 à 100, calculé par la fonction qui note un vrai déploiement |
reason | string ou null | La retenue principale (« −30 site non indexable »), null quand tout est passé |
outcome | "pass" ou "fail" | pass si aucune ligne n'est en fail ni en error ; c'est le champ sur lequel faire échouer une étape |
failed | number | Le nombre de lignes en fail ou error |
checks[] | array | Une ligne par vérification (voir ci-dessous) |
checks[].kind | string | http, index, og, sitemap, ssl, ia |
checks[].label | string | Le nom lisible : Page et ressources, Indexabilité, Carte sociale, Sitemap, Certificat SSL, Visibilité IA |
checks[].outcome | string | pass, fail, error (PostShip n'a pas pu conclure : délai, DNS), ou skip (rien à vérifier — un site sans sitemap) |
checks[].detail | string | Une phrase, celle qu'une personne dirait : « Statut 200 · 412 ms », « ChatGPT ne peut pas vous lire » |
quota.used | number | Les vérifications consommées ce mois-ci, celle-ci comprise |
quota.limit | number | Le plafond du plan : 30, 300 ou 1000 |
quota.remaining | number | Ce qui reste |
Une ligne skip ne pèse pas sur la note ni sur outcome : un site sans sitemap n'a rien cassé. Une ligne error compte comme un échec — un certificat illisible ou une page qui ne répond pas dans les délais est un problème, pas une absence de problème.
Ce que les six lignes regardent est décrit sur la page du scan public : c'est le même audit, sous un budget de 40 requêtes vers le site.
Les codes HTTP
| Code | Quand | Corps |
|---|---|---|
200 | La vérification a eu lieu, quel que soit son verdict | L'objet ci-dessus |
400 | Corps illisible ou sans url | {"error":"URL invalide (https requis)."} |
400 | URL refusée | {"error":"L'URL doit être en https."}, {"error":"URL invalide (identifiants non autorisés)."}, ou la raison de la garde réseau |
401 | Jeton invalide ou révoqué | {"error":"Jeton d'API invalide ou révoqué."} |
429 | Quota du mois atteint | {"error":"Quota mensuel atteint (300/300 vérifications).","quota":{"used":300,"limit":300,"remaining":0}} |
Un 200 avec outcome: "fail" est une réponse normale : le site a un problème. Un 4xx veut dire que la vérification n'a pas eu lieu. Une CI doit distinguer les deux — voir Vérifier depuis votre CI pour les codes de sortie.
Limites et plans
| Free | Pro | Team | |
|---|---|---|---|
| Vérifications par mois | 30 | 300 | 1000 |
Par mois calendaire (UTC) et par compte, tous jetons confondus, avec l'outil MCP run_check. La place est réservée avant l'audit, atomiquement : des appels lancés en parallèle ne dépassent pas la limite. Voir API et les plans.
Dépannage
Pourquoi la réponse met-elle vingt secondes ?
Les six vérifications tournent en parallèle sous un budget partagé ; la réponse arrive dans le temps de la plus lente, en général celle des ressources ou du sitemap sur un site lent. Prévoyez un délai d'au moins 60 secondes côté client.
Pourquoi outcome est-il fail alors que le score est à 90 ?
Une ligne en error fait échouer outcome mais ne coûte que dix points (« URL en échec »). C'est voulu : un score sert à comparer, un verdict sert à bloquer. Regardez checks[] pour la ligne en cause.
Pourquoi la ligne sitemap est-elle skip alors que mon sitemap existe ?
Il n'est pas déclaré dans robots.txt (Sitemap:) et n'est pas à /sitemap.xml sur la même origine. Déclarez-le dans robots.txt : c'est là que les moteurs le cherchent aussi.