Most of the time, checking on a site means logging into the portal. Sometimes that's the wrong tool — you want a script that pings uptime every morning, or you'd rather just ask an AI assistant “is anything down” than open a browser tab. The Platform API and the MCP server exist for exactly that: the same data your portal shows you, reachable from code or from an LLM client, behind one key. This guide is the practical version — how to get a key, what it can touch, and two ways to actually call it.
What the Platform API is
It's a plain REST API under /api/v1 — JSON in, JSON out, one Bearer key on every request. It is not a separate product with its own data model: every endpoint reads and writes through the same tables your portal, agency console, or admin panel already use, so a site's status through the API is never stale relative to what you'd see by logging in. The full endpoint index is published, unauthenticated, at GET /api/v1 — it's the same list rendered as a table on the /developers page, generated straight from the route definitions rather than hand-copied, so it can't drift out of date.
Getting a key
Key issuance is admin-gated by default. Two paths, depending on your account:
- An admin issues a key for your account from the platform side — no setup needed on your end, and this works for any account today.
- If your account's self-serve API access has been switched on, you can issue your own key from your own settings page — clients and agencies both get this once the toggle is on. The toggle defaults off; ask if you want it enabled.
A key looks like hf_live_ followed by 43 random characters, and it is shown exactly once, at the moment it's created. Only its cryptographic hash is ever stored after that — there is no “view key again” screen, by design, the same discipline as a password. Copy it somewhere safe immediately, and treat it the way you'd treat any credential: never in a client-side script, never pasted into a chat log, never committed to a repo.
The scope model, in plain terms
A key doesn't get to do everything its owner could theoretically do — it gets a fixed set of scopes, baked in at the moment it's issued, based on the account's role at that instant. A client account's key can read and act on that client's own sites, requests, and restores. An agency account's key adds the ability to read its managed end-clients and provision new sites under them. An admin key adds fleet-wide read access and the handful of admin actions (billing dunning, suspension control). If a role changes later — say, a client account is promoted to agency — keys issued before that change keep their old, narrower scopes until reissued. That's deliberate: a key silently gaining new powers because someone's role changed elsewhere is a worse surprise than “go issue a new key.”
Every scope follows a read/write split — client:read, client:write, agency:read, agency:write, admin:read, admin:write — and both the REST API and the MCP tool list enforce the identical scopes, the identical way. The full scope table lives on /developers; this guide won't duplicate it.
A couple of real calls
Two endpoints that actually exist today, called exactly as written:
| What it does | Call |
|---|---|
| List every site the key can see | curl https://hostfluency.com/api/v1/sites -H "Authorization: Bearer hf_live_<your key>" |
| One site's detail — plan, status, and a 30-day uptime summary | curl https://hostfluency.com/api/v1/sites/42 -H "Authorization: Bearer hf_live_<your key>" |
A missing or wrong key returns a plain 401; a key that resolves but lacks the scope a route needs returns a 403; too many requests in a short window returns a 429 with a retry-after hint. Nothing about the failure modes is a guessing game.
MCP: the same access, from an AI assistant
MCP — the Model Context Protocol — is an open standard that lets an AI assistant call an application's tools directly, the way a human would click buttons in an app, instead of you copying API responses into a chat window by hand. Hostfluency runs a remote MCP server at POST /api/mcp, authenticated with the exact same Bearer key as the REST API, exposing the same data as a set of named tools an MCP-aware client can call on its own.
To connect Claude (or any other MCP-compatible client), add a remote connector pointed at https://hostfluency.com/api/mcp with your key as the Bearer token. No install, no local process — the connection is just that URL and that header. Once it's connected, a tool list is offered to the assistant automatically, already filtered down to whatever your key's scopes allow; nothing outside your own scope is ever visible to it, let alone callable.
What's available today
The MCP tool list and the REST endpoint index are both generated from the server's own definitions, and both are published in full on /developers — this guide points there rather than duplicating either table, since a copy here would eventually drift. One honest gap worth naming: DNS record management, covered in the companion guide, currently lives only in the portal, agency console, and admin panel — it is not yet exposed through the Platform API or as an MCP tool. If you need to script or ask an assistant about DNS specifically, that's on the roadmap, not shipped yet.
Everything else — sites, uptime, support requests, restores, billing state, and for agencies, client rosters and provisioning — is live on both surfaces today, with the same scopes enforced the same way whichever door you come in through.
Filed under api & mcp · HF-G-005
Still a question? Ask us — same-day answers.