Foxguide public API
The public HTTP API — how to authenticate, what a refusal looks like, how pages and webhooks work, and the full endpoint reference.
The public API is served at https://api.foxguide.io. Every request is
authenticated with an API token, and every token carries an explicit list of
scopes. Nothing is granted by default — a token reaches only what it was
issued for.
curl https://api.foxguide.io/v1/tables \
-H 'Authorization: Bearer fgd_live_...'New here? Start with Getting started — how a token is issued, and the one property of it that surprises people (the secret is shown exactly once).
What each guide answers
| guide | the question it answers |
|---|---|
| Getting started | How do I get a token and make my first call? |
| Authentication | What is a scope, and why was I refused? |
| Errors | What shape is an error, and should I retry it? |
| Pagination | How do I walk a collection without missing rows? |
| Rate limits | How many requests do I get, and what does 429 mean? |
| Versioning and deprecation | What can change under me, and how much warning do I get? |
| Webhooks | How do I verify a delivery, and how do I send one? |
| Changelog | What changed, and when? |
The endpoint reference is generated from the published OpenAPI
document and is the authority for every path, parameter and response shape. The
document itself is at /openapi/public-openapi.yaml
if you would rather generate a client than read a page.
The contract is opt-in
An endpoint is part of the public API only when it declares itself so. The reference and the surface a token can reach are generated from the same declaration, so they cannot drift: what is documented is exactly what is reachable, and a route absent from the reference answers 403 rather than working undocumented.
Three consequences worth internalising before you build:
- Default-deny is real. A token with no matching scope is refused, and a token with no scope list at all is refused too — an absent list is treated exactly like an empty one.
- Additive change ships without notice. Ignore response fields you do not
recognise, and fall back to the HTTP status for an
errorcode you have not seen. - Anything non-additive carries a published notice period. Six months, announced in the changelog and in two response headers.
Not yet available
Three things a developer reasonably expects from an API of this shape do not exist yet. They are listed on this page — with the reason for each — so their absence reads as a roadmap rather than as an oversight you have to discover by trying. See the panel below.
Guides
- Getting started
How to obtain an API token, make a first authenticated request, and read the response.
- Authentication
Bearer API tokens, the entity-plus-action scope model, and why default-deny means an unscoped token is refused rather than allowed.
- Errors
The one flat error envelope every endpoint returns, the status codes it is paired with, and which refusals are worth retrying.
- Pagination
The offset and cursor envelopes, and why the total count is sometimes absent rather than zero.
- Rate limits
Per-token request limits, the default and the maximum, and what a 429 tells you to do next.
- Versioning and deprecation
How the API is versioned, and the notice you receive before anything is withdrawn.
- Webhooks
How outbound webhook deliveries are signed, and how a receiver verifies a signature.
- Changelog
Dated, human-readable entries for every change to the public API surface.
- API reference
Every endpoint of the public API, generated from the machine-readable contract.
Not yet available
These are named here deliberately, so their absence reads as a roadmap rather than an oversight. The API does not have them today, and this documentation will not describe behaviour the API does not have.
- Idempotency keys
- The Idempotency-Key header is not implemented. Documenting a header the API ignores is worse than omitting it.
- Client libraries / SDKs
- None exist yet. The OpenAPI specification is machine-readable, so a generated client is available to you today.
- Sandbox / test mode
- There is no test-key mode. fgd_live_ is the only token prefix, and it addresses live data.