Skip to Content
FontegoDocs

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: NAME says 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" } }
StatusWhen
401no token, or a token that isn't valid any more
403signed in, but not allowed (a reader writing, a non-admin on an admin route)
404not found, also for a workspace you aren't a member of
409a conflict: the file changed meanwhile, or the workspace is archived
415a body without Content-Type: application/json
422refused content: a protected or rejected path, a secret, a file too big
429too many anonymous calls or failed sign-ins from your address
503the 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.

On this page