Développeurs : documentation de l'API

La surface publique est décrite en OpenAPI 3.1 à /openapi.json : chaque point d'accès de cette page, ses réponses et la forme de ses erreurs. Chaque page l'annonce aussi dans un en-tête Link avec rel="service-desc".

curl -s https://fiveshield.co/openapi.json

• openapi.json

• Les points d'accès marqués Aucune ci-dessous n'exigent ni authentification ni clé d'API.
• L'agent s'enrôle une seule fois avec un jeton à usage unique que le tableau de bord génère à l'étape 5 du guide d'installation, puis signe chaque requête par un HMAC dans les en-têtes X-FS-*. Ces deux points d'accès sont réservés à l'agent : ne les appelez pas à la main.
• L'API propre au tableau de bord (/api/auth et /api/server) utilise votre session de connexion Discord, stockée dans un cookie du navigateur. Elle est réservée au tableau de bord, n'est pas décrite dans le document OpenAPI et n'est pas proposée comme interface pour développeurs.

• GET/api/health

  Sonde de vie en JSON : état, identifiant de la version déployée et centre de données qui a répondu. Jamais mise en cache.

  Authentification : Aucune

• HEAD/api/health

  Les mêmes en-têtes, sans corps.

  Authentification : Aucune

• GET/health

  La même sonde en texte brut (ok). /healthz en est un alias.

  Authentification : Aucune

La sonde indique que le site web lui-même fonctionne. Elle n'interroge pas le réseau de proxys : pour cela, utilisez la page de statut.

curl -s https://fiveshield.co/api/health

{"status":"ok","version":"<build id>","colo":"YYZ","time":"2026-10-25T04:00:00.000Z"}

• Page de statut en direct (s'ouvre dans un nouvel onglet)

Les clients installent l'agent fiveshield sur leur propre serveur pour protéger l'origine. Ses téléchargements et son API sont servis depuis fiveshield.co. Le tableau de bord génère la commande d'installation complète sur une ligne, jeton d'enrôlement compris : utilisez cette commande plutôt que ces adresses seules.

• GET/install.sh

  L'installateur Linux.

  Authentification : Aucune

• GET/install.ps1

  L'installateur Windows.

  Authentification : Aucune

• GET/agent/{binary}

  Les versions de l'agent : Linux x86_64 et aarch64, et Windows x86_64. Jamais mises en cache.

  Authentification : Aucune

• POST/api/agent/enroll

  Échange le jeton d'enrôlement contre les identifiants de l'agent.

  Authentification : Jeton à usage unique dans le corps

• POST/api/agent/reconcile

  L'agent rapporte son état et reçoit sa configuration.

  Authentification : Signature HMAC dans les en-têtes X-FS-*

Un téléchargement qui échoue répond par un commentaire shell d'une ligne plutôt que par une page d'erreur : envoyer un installateur dans un shell n'exécute donc jamais une erreur. Une tentative d'enrôlement échouée compte contre votre adresse : n'appelez pas /api/agent/enroll à la main.

Les erreurs que ce site produit lui-même sous /api sont en JSON : une raison stable (error), un code, le statut, un message et une indication de ce qu'il faut faire.

curl -s -X POST https://fiveshield.co/api/health

{
  "error": "method_not_allowed",
  "code": "method_not_allowed",
  "status": 405,
  "message": "This route does not accept that HTTP method.",
  "hint": "Use one of the methods listed in the Allow response header, or in the OpenAPI description.",
  "docs": "https://fiveshield.co/openapi.json"
}

Les points d'accès de l'agent répondent une forme plus étroite, {"error":{"code":"..."}}, car l'agent la lit.

Demandez n'importe quelle page avec Accept: text/markdown et elle est servie en Markdown, avec Vary: Accept. Une page qui n'existe pas répond aussi 404 en Markdown, avec des liens pour revenir dans le site.

curl -s -H 'Accept: text/markdown' https://fiveshield.co/en

Ces fichiers décrivent le site aux programmes :

• GET/llms.txt

  Un plan du site en texte brut : ce qu'est le service, chaque page publique en français et en anglais, les tarifs, les emplacements et le support.

  Authentification : Aucune

• GET/sitemap.xml

  Toutes les pages publiques, avec leurs alternatives de langue.

  Authentification : Aucune

• GET/.well-known/agent-skills/index.json

  Les compétences (skills) que ce site publie pour les agents, chacune avec une empreinte SHA-256.

  Authentification : Aucune

• GET/openapi.json

  La description OpenAPI 3.1 de tout ce qui figure sur cette page.

  Authentification : Aucune

• Les requêtes sont limitées par adresse. Une réponse 429 signifie qu'il faut ralentir : attendez le nombre de secondes indiqué par son en-tête Retry-After, puis réessayez.
• Pour tout le reste, demandez sur Discord en précisant l'heure et le chemin de la requête.

• Support sur Discord (s'ouvre dans un nouvel onglet)
• Comment fonctionne FIVESHIELD