Developers: API documentation

The public surface is described in OpenAPI 3.1 at /openapi.json: every endpoint on this page, its responses and its error shapes. Every page also advertises it in a Link header with rel="service-desc".

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

• openapi.json

• The endpoints marked None below need no authentication and no API key.
• The host agent enrols once with a single-use token that the dashboard generates in step 5 of the install guide, then signs each request with an HMAC in the X-FS-* headers. Those two endpoints are for the agent, not for calling by hand.
• The dashboard's own API (/api/auth and /api/server) uses your Discord sign-in session in a browser cookie. It is for the dashboard only, is not described in the OpenAPI document and is not offered as a developer interface.

• GET/api/health

  Liveness probe as JSON: status, the build id and the data centre that answered. Never cached.

  Authentication: None

• HEAD/api/health

  The same headers, no body.

  Authentication: None

• GET/health

  The same probe as plain text (ok). /healthz is an alias.

  Authentication: None

The probe says the website itself is running. It makes no call to the proxy network, so use the status page for that.

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

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

• Live status page (opens in a new tab)

Customers install the host agent on their own server to protect the origin. Its downloads and API are served from fiveshield.co. The dashboard generates the complete one-line install command, including the enrolment token, so use that command rather than these URLs on their own.

• GET/install.sh

  The Linux installer.

  Authentication: None

• GET/install.ps1

  The Windows installer.

  Authentication: None

• GET/agent/{binary}

  The agent builds: Linux x86_64 and aarch64, and Windows x86_64. Never cached.

  Authentication: None

• POST/api/agent/enroll

  Exchanges the enrolment token for agent credentials.

  Authentication: Single-use token in the body

• POST/api/agent/reconcile

  The agent reports its state and receives its configuration.

  Authentication: HMAC signature in the X-FS-* headers

A download that fails answers a one-line shell comment instead of an error page, so piping an installer into a shell never runs one. A failed enrolment attempt counts against your address: do not call /api/agent/enroll by hand.

Errors this site produces itself under /api are JSON: a stable error reason, a code, the status, a message and a hint that says what to do about it.

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"
}

The host agent endpoints answer a narrower shape, {"error":{"code":"..."}}, because the agent parses it.

Request any page with Accept: text/markdown and it is answered as Markdown, with Vary: Accept. A page that does not exist answers 404 in Markdown too, with links back into the site.

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

These files describe the site to programs:

• GET/llms.txt

  A plain-text map of the site: what the service is, every public page in English and French, pricing, locations and support.

  Authentication: None

• GET/sitemap.xml

  Every public page, with its alternates.

  Authentication: None

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

  The skills this site publishes for agents, each with a SHA-256 digest.

  Authentication: None

• GET/openapi.json

  The OpenAPI 3.1 description of everything on this page.

  Authentication: None

• Requests are rate limited per address. An answer of 429 means slow down: wait the number of seconds in its Retry-After header, then retry.
• For anything else, ask on Discord and quote the time and the path of the request.

• Support on Discord (opens in a new tab)
• How FIVESHIELD works