API

L'API de PostShip fait deux choses, et deux seulement : lancer une vérification sur une URL — la même que le cycle et le scan public — et lire l'état de vos projets depuis vos propres outils. Tout est en JSON, sur https://postship.fr/api/v1/, avec un jeton en en-tête. Aucune route n'écrit dans un projet, et il n'en existera pas : un jeton d'API vit dans une variable d'environnement de CI, et une suppression au bout de celui-là serait à un copier-coller de distance. Ce qui modifie un projet passe par l'application, où quelqu'un est connecté.

Authentification

Un jeton psk_…, créé depuis Paramètres → API & tokens, passé dans l'en-tête Authorization. Le même jeton sert à toutes les routes et au serveur MCP.

export POSTSHIP_TOKEN=psk_…

curl -sS https://postship.fr/api/v1/projects \
  -H "Authorization: Bearer $POSTSHIP_TOKEN"

Le jeton passe par une variable d'environnement, jamais en argument d'une commande : un argument se lit dans la liste des processus du runner, où le masquage des secrets ne s'applique pas. Un jeton invalide ou révoqué répond 401 avec {"error":"Jeton d'API invalide ou révoqué."}, sur toutes les routes de la même façon. PostShip ne garde que l'empreinte SHA-256 du jeton et note la date de sa dernière utilisation — c'est ce qui permet d'en révoquer un sans se demander s'il tourne encore quelque part.

Un jeton voit exactement ce que son propriétaire voit : ses projets, et ceux qu'on lui a partagés en tant que membre accepté. Une invitation en attente n'en est pas un.

Les routes

La lecture ne consomme pas votre compteur mensuel. Ce compteur paie du travail réel — des requêtes vers votre site ; une lecture ne coûte qu'une requête à notre base. Les mélanger vous ferait payer un tableau de bord au prix d'une sonde.

Le format

Les réponses sont en JSON, en UTF-8, avec Cache-Control: no-store sur les lectures : une réponse d'API ne se met pas en cache. Les dates sont en ISO 8601 (UTC). Les erreurs portent toujours un champ error avec une phrase en français, et parfois un champ de plus (quota sur un 429) :

{ "error": "Quota mensuel atteint (300/300 vérifications).", "quota": { "used": 300, "limit": 300, "remaining": 0 } }

Les codes HTTP

Un projet qui n'existe pas et un projet qu'on n'a pas le droit de voir répondent la même chose. Les distinguer confirmerait l'existence d'un identifiant à qui le devine — et un identifiant confirmé est la moitié du travail d'un inventaire.

Limites et plans

Les vérifications lancées par l'API sont comptées par mois calendaire (UTC) et par compte, tous jetons confondus, POST /check et l'outil MCP run_check ensemble.

Au-delà du quota, l'appel est refusé avec le compte exact — jamais un résultat dégradé : une CI qui ment est pire qu'une CI qui casse. La place est prise avant la vérification, de façon atomique : cent appels lancés en parallèle ne passent pas tous sous la limite. Le compteur du mois se lit dans Paramètres → API & tokens (« 12/300 vérifications de CI ce mois-ci »). Voir les plans.

Dépannage

Pourquoi 401 alors que le jeton vient d'être créé ?

Vérifiez l'en-tête : Authorization: Bearer psk_…, avec l'espace après Bearer, et le jeton entier — il commence par psk_ et n'est affiché qu'une fois. Un jeton révoqué ne revient pas : créez-en un autre.

Pourquoi 404 sur un projet que je vois dans l'application ?

Le jeton appartient à un autre compte que celui qui voit le projet, ou vous êtes invité sur ce projet sans avoir accepté l'invitation. Un jeton ne voit que les projets de son propriétaire et ceux où il est membre accepté.

Pourquoi le quota a-t-il baissé sans que ma CI ait tourné ?

Le compteur est par compte : un autre jeton du même compte, ou l'outil MCP run_check depuis un éditeur, consomme la même réserve. La date de dernière utilisation de chaque jeton, dans Paramètres → API & tokens, dit lequel a servi.