The API
How to call the Fontego API: tokens, errors, headers and the index every server publishes.
Everything goes through one HTTP API under /v1: the web app, the CLI and your own scripts use the same routes, with
the same rules. Every route is in the API reference.
The index
A running server describes itself:
GET /v1: every route, who may call it, the command that uses it, and the JSON Schema of its query and body.GET /v1/commands: the commands it declares for the CLI.GET /v1/health: for monitoring and load balancers.
Authentication
Send a token in the Authorization header:
curl -H "Authorization: Bearer $FONTEGO_TOKEN" https://fontego.example.org/v1/workspaces- Tokens an admin creates (
fontego admin tokens create) don't expire; they are revoked by hand. - A CLI's session signs in with OAuth for native apps (an authorization code with PKCE, or the device flow) and gets an access token that lasts an hour, plus a refresh token that is swapped for a new one on every use. A refresh token used twice closes the session.
The web app uses a session cookie instead. With the cookie, every change also needs the header
X-Requested-With: fontego-web, which a page on another site can't send.
Requests
- A JSON body needs
Content-Type: application/json; otherwise the answer is 415. fontego-agent: NAMEsays which agent makes the call. The logs and the commits note it; it grants nothing.
Answers and errors
Errors come as:
{ "error": { "code": "not_found", "message": "…", "hint": "what to do next" } }| Status | When |
|---|---|
| 401 | no token, or a token that isn't valid any more |
| 403 | signed in, but not allowed (a reader writing, a non-admin on an admin route) |
| 404 | not found, also for a workspace you aren't a member of |
| 409 | a conflict: the file changed meanwhile, or the workspace is archived |
| 415 | a body without Content-Type: application/json |
| 422 | refused content: a protected or rejected path, a secret, a file too big |
| 429 | too many anonymous calls or failed sign-ins from your address |
| 503 | the server is busy checking passwords; try again |
Every answer carries a fontego-commands header with the version of the server's commands, so a client knows when its
saved copy is stale.
Live events
GET /v1/workspaces/{workspace}/events is a stream of server-sent events: a ready event first, then one event per
commit to that workspace. fontego watch uses it to sync as soon as someone else changes something.