API routes
Every route of the Fontego API: who may call it, what it takes and which command uses it.
Every route of the API, as the server declares it. A running server lists the same at GET /v1, with the
JSON Schema of each query and body. How to call it (tokens, errors, headers) is in the
API overview.
The server
GET /v1
This index: every endpoint, who may call it, what it takes and its CLI command.
- Who: anyone
- CLI: none. the API's own description, for people and agents reading the API.
GET /v1/health
Whether the server is up, and its version.
- Who: anyone
- CLI: none. for monitoring and load balancers.
GET /v1/commands
The CLI commands this server declares; every answer carries their version in the fontego-commands header.
- Who: anyone
- CLI:
fontego help
GET /v1/instance
What this server is, how long its sessions last, and where its CLI signs in (OAuth endpoints).
- Who: anyone
- CLI:
fontego login
Accounts
GET /v1/me
Who you are, and with which token.
- Who: anyone signed in
- CLI:
fontego whoami
POST /v1/password-reset
Mail a link to set a new password; the answer is the same whether the address has an account or not.
- Who: anyone
- CLI:
fontego password-reset
| Body (JSON) | Type | |
|---|---|---|
email | string | Required. |
GET /v1/links/{token}
What a one-time link is for (set up an account, accept an invitation, reset a password).
- Who: anyone
- CLI: none. proving who you are stays in the browser.
POST /v1/links/{token}
Use a one-time link: set the password, spend the link and sign the browser in.
- Who: anyone
- CLI: none. proving who you are stays in the browser.
| Body (JSON) | Type | |
|---|---|---|
password | string | Required. at least 15 characters, at most 256 characters. |
name | string | at most 200 characters. |
Sessions and signing in
POST /v1/session
Sign a browser in, with email and password, a token, or a one-time code; the session goes in an HttpOnly cookie.
- Who: anyone
- CLI: none. proving who you are stays in the browser.
Body (JSON): object \\| object \\| object
DELETE /v1/session
Sign the browser out: its session closes.
- Who: anyone
- CLI: none. proving who you are stays in the browser.
POST /v1/session/code
A one-time link that opens the web app already signed in (valid two minutes).
- Who: anyone signed in
- CLI:
fontego open
POST /v1/oauth/authorize
From a signed-in browser: connect a CLI (or refuse); answers where to send the browser back.
- Who: anyone signed in
- CLI: none. proving who you are stays in the browser.
| Body (JSON) | Type | |
|---|---|---|
client_id | string | Required. |
redirect_uri | string | Required. |
code_challenge | string | Required. |
code_challenge_method | string | Required. |
state | string | at most 500 characters. |
machine | string | at most 80 characters. |
approve | boolean | Required. |
POST /v1/oauth/device
A CLI without a browser asks to sign in: a short code for the person to type at /device (RFC 8628).
- Who: anyone
- CLI:
fontego login
| Body (JSON) | Type | |
|---|---|---|
client_id | string | Required. |
machine | string | at most 80 characters. |
GET /v1/oauth/device/{code}
From a signed-in browser: which machine a device code would connect.
- Who: anyone signed in
- CLI: none. proving who you are stays in the browser.
POST /v1/oauth/device/{code}
From a signed-in browser: connect the machine of a device code, or refuse.
- Who: anyone signed in
- CLI: none. proving who you are stays in the browser.
| Body (JSON) | Type | |
|---|---|---|
approve | boolean | Required. |
POST /v1/oauth/token
OAuth token endpoint (form or JSON): an authorization code with PKCE, a device code or a refresh token, for an access token (one hour) and a new refresh token.
- Who: anyone
- CLI:
fontego login
POST /v1/oauth/revoke
Close the session of an access or refresh token (RFC 7009); answers 200 even for unknown tokens.
- Who: anyone
- CLI:
fontego logout
Workspaces
GET /v1/workspaces
The workspaces you can see, with your role in each.
- Who: anyone signed in
- CLI:
fontego workspaces
| Query | Type | |
|---|---|---|
category | string |
POST /v1/workspaces
Create a workspace; whoever creates it becomes its admin.
- Who: server admins
- CLI:
fontego workspace create
| Body (JSON) | Type | |
|---|---|---|
slug | string | Required. |
name | string | at most 200 characters. |
description | string | at most 5000 characters. |
category | string | at most 100 characters. |
template | string | |
git | string | at most 2000 characters. |
branch | string | at most 200 characters. |
history | boolean |
GET /v1/templates
The templates a new workspace can start from.
- Who: server admins
- CLI:
fontego workspace templates
GET /v1/workspaces/{workspace}
A workspace: description, category, your role and its last change.
- Who: readers of the workspace
- CLI:
fontego workspace info
PATCH /v1/workspaces/{workspace}
Change a workspace's name, description or category.
- Who: admins of the workspace
- CLI:
fontego workspace edit
| Body (JSON) | Type | |
|---|---|---|
name | string | at most 200 characters. |
description | string | at most 5000 characters. |
category | string | at most 100 characters. |
GET /v1/workspaces/{workspace}/members
Who is in a workspace, with which role.
- Who: readers of the workspace
- CLI:
fontego members
PUT /v1/workspaces/{workspace}/members/{email}
Give someone with an account a role in a workspace.
- Who: admins of the workspace
- CLI:
fontego members set
| Body (JSON) | Type | |
|---|---|---|
role | `"reader" \ | "editor" \ |
DELETE /v1/workspaces/{workspace}/members/{email}
Take someone out of a workspace.
- Who: admins of the workspace
- CLI:
fontego members remove
GET /v1/workspaces/{workspace}/paths
The paths a workspace protects (only its admins write them) and rejects (nobody writes them).
- Who: readers of the workspace
- CLI:
fontego workspace paths
PUT /v1/workspaces/{workspace}/paths/protected/{+pattern}
Protect a path: only the workspace's admins can write it. The workspace gets its own list, starting from the instance's.
- Who: admins of the workspace
- CLI:
fontego workspace paths protect
DELETE /v1/workspaces/{workspace}/paths/protected/{+pattern}
Stop protecting a path.
- Who: admins of the workspace
- CLI:
fontego workspace paths unprotect
PUT /v1/workspaces/{workspace}/paths/rejected/{+pattern}
Reject a path: nobody can write it (server admins only).
- Who: admins of the workspace
- CLI:
fontego workspace paths reject
DELETE /v1/workspaces/{workspace}/paths/rejected/{+pattern}
Stop rejecting a path (server admins only).
- Who: admins of the workspace
- CLI:
fontego workspace paths unreject
DELETE /v1/workspaces/{workspace}/paths
Go back to the instance's default paths, for both kinds or one (the rejected ones: server admins only).
- Who: admins of the workspace
- CLI:
fontego workspace paths reset
| Query | Type | |
|---|---|---|
kind | `"protected" \ | "rejected"` |
Files
GET /v1/workspaces/{workspace}/tree
The files and folders in a folder (recursive=1 for everything below it).
- Who: readers of the workspace
- CLI:
fontego ls
| Query | Type | |
|---|---|---|
path | string | |
rev | string | |
recursive | string |
GET /v1/workspaces/{workspace}/files/{+path}
A file's content (meta=1 for its hash, mode and size instead; download=1 to save it).
- Who: readers of the workspace
- CLI:
fontego cat
| Query | Type | |
|---|---|---|
rev | string | |
meta | string | |
download | string |
GET /v1/workspaces/{workspace}/history
Commits, newest first, of the workspace or of one path.
- Who: readers of the workspace
- CLI:
fontego log
| Query | Type | |
|---|---|---|
path | string | |
rev | string | |
limit | string |
GET /v1/workspaces/{workspace}/sync
What changed since a commit, for keeping a copy in step (reset=true: take it as the full tree).
- Who: readers of the workspace
- CLI:
fontego clone,fontego link,fontego sync,fontego watch
| Query | Type | |
|---|---|---|
since | string |
GET /v1/workspaces/{workspace}/search
Find text in the workspace's files.
- Who: readers of the workspace
- CLI:
fontego search
| Query | Type | |
|---|---|---|
q | string | Required. |
path | string | |
limit | string |
POST /v1/workspaces/{workspace}/changes
Write: whole files plus the hash each edit started from; text changed on both sides is merged.
- Who: editors of the workspace
- CLI:
fontego clone,fontego link,fontego sync,fontego watch
| Body (JSON) | Type | |
|---|---|---|
baseCommit | `string \ | null` |
message | string | at most 10000 characters, default "". |
ops | any[] | Required. |
client | string | at most 40 characters. |
GET /v1/workspaces/{workspace}/events
Server-Sent Events: ready, then commit on every change.
- Who: readers of the workspace
- CLI:
fontego watch
PUT /v1/workspaces/{workspace}/files/{+path}
Write one whole file: without baseHash only a new one; with it, an edit of that version (text changed elsewhere meanwhile is merged).
- Who: editors of the workspace
- CLI:
fontego write
| Body (JSON) | Type | |
|---|---|---|
content | string | |
contentBase64 | string | |
baseHash | `string \ | null` |
mode | `"100644" \ | "100755" \ |
message | string | at most 10000 characters. |
DELETE /v1/workspaces/{workspace}/files/{+path}
Delete one file, naming the version you delete (baseHash): if it changed since, nothing is deleted.
- Who: editors of the workspace
- CLI:
fontego rm
| Body (JSON) | Type | |
|---|---|---|
baseHash | string | |
message | string | at most 10000 characters. |
POST /v1/workspaces/{workspace}/move
Move or rename one file, naming the version you move (baseHash); the new name must be free.
- Who: editors of the workspace
- CLI:
fontego mv
| Body (JSON) | Type | |
|---|---|---|
from | string | Required. |
to | string | Required. |
baseHash | string | |
message | string | at most 10000 characters. |
Server admin
GET /v1/admin/users
Everyone with an account on this server, and whether they can sign in.
- Who: server admins
- CLI:
fontego admin users
POST /v1/admin/users/invitations
Invite someone: creates their account and mails them a link to set their password (valid 7 days).
- Who: server admins
- CLI:
fontego admin users invite
| Body (JSON) | Type | |
|---|---|---|
email | string | Required. |
name | string | at most 200 characters. |
admin | boolean |
POST /v1/admin/users/{email}/invitation
Send a new invitation link to someone who hasn't set a password yet; the earlier one stops working.
- Who: server admins
- CLI:
fontego admin users resend
POST /v1/admin/users/{email}/disable
Stop someone from signing in, and close their sessions, CLI logins and agent tokens at once.
- Who: server admins
- CLI:
fontego admin users disable
POST /v1/admin/users/{email}/enable
Let someone who was disabled sign in again.
- Who: server admins
- CLI:
fontego admin users enable
POST /v1/admin/users
Create an account without a password, for tokens only (to invite a person, use /users/invitations).
- Who: server admins
- CLI:
fontego admin users add
| Body (JSON) | Type | |
|---|---|---|
email | string | Required. |
name | string | at most 200 characters. |
isAdmin | boolean |
POST /v1/admin/users/{email}/tokens
Create a token for someone, or for their agent.
- Who: server admins
- CLI:
fontego admin tokens create
| Body (JSON) | Type | |
|---|---|---|
label | string | at most 200 characters. |
kind | `"person" \ | "agent"` |
GET /v1/admin/mail
How this server sends mail: through which SMTP, or not at all.
- Who: server admins
- CLI:
fontego admin mail
GET /v1/admin/mail/outbox
Messages that couldn't go out (no SMTP, or sending failed), with the link to pass on by hand.
- Who: server admins
- CLI:
fontego admin mail outbox
POST /v1/admin/mail/test
Send a test message, to check the SMTP settings.
- Who: server admins
- CLI:
fontego admin mail test
| Body (JSON) | Type | |
|---|---|---|
to | string | Required. |
GET /v1/admin/settings
The instance's settings: each one's value and where it comes from (the server's config wins).
- Who: server admins
- CLI:
fontego admin settings
GET /v1/admin/settings/{key}
One setting: its value, what it is for, and where it comes from.
- Who: server admins
- CLI:
fontego admin settings get
PUT /v1/admin/settings/{key}
Change a setting at once; refused if the server's config sets it. A secret (the SMTP password) is never shown again.
- Who: server admins
- CLI:
fontego admin settings set
| Body (JSON) | Type | |
|---|---|---|
value | `string \ | number \ |
DELETE /v1/admin/settings/{key}
Forget what an admin set: the server's config or the default applies again.
- Who: server admins
- CLI:
fontego admin settings reset
DELETE /v1/admin/users/{email}
Delete an account at once, with its sessions, tokens and memberships; what it wrote stays in the history.
- Who: server admins
- CLI:
fontego admin users remove
| Body (JSON) | Type | |
|---|---|---|
confirm | boolean | Required. |
PUT /v1/admin/users/{email}/admin
Make someone a server admin.
- Who: server admins
- CLI:
fontego admin users grant-admin
DELETE /v1/admin/users/{email}/admin
Stop someone being a server admin; the server always keeps one.
- Who: server admins
- CLI:
fontego admin users revoke-admin
POST /v1/admin/users/{email}/password-reset
Send someone a link to set a new password (or get it to pass on, without mail).
- Who: server admins
- CLI:
fontego admin users reset-password
GET /v1/admin/sessions
Open sessions (browsers and CLIs) of everyone, or of one person.
- Who: server admins
- CLI:
fontego admin sessions
| Query | Type | |
|---|---|---|
user | string |
DELETE /v1/admin/sessions/{id}
Close someone's session at once.
- Who: server admins
- CLI:
fontego admin sessions close
GET /v1/admin/tokens
Tokens that still work, of everyone or of one person (they don't expire).
- Who: server admins
- CLI:
fontego admin tokens
| Query | Type | |
|---|---|---|
user | string |
DELETE /v1/admin/tokens/{id}
Revoke a token at once.
- Who: server admins
- CLI:
fontego admin tokens revoke
GET /v1/admin/workspaces
Every workspace, also those you're not a member of and the archived ones, with how many members each has.
- Who: server admins
- CLI:
fontego admin workspaces
PUT /v1/admin/workspaces/{workspace}/archived
Archive a workspace: it leaves everyone's lists and can be read, not changed, until it is brought back.
- Who: server admins
- CLI:
fontego admin workspaces archive
DELETE /v1/admin/workspaces/{workspace}/archived
Bring an archived workspace back, as it was.
- Who: server admins
- CLI:
fontego admin workspaces unarchive
DELETE /v1/admin/workspaces/{workspace}
Delete an archived workspace for good: its files, its history and its members. Its id, typed again, confirms it.
- Who: server admins
- CLI:
fontego admin workspaces delete
| Body (JSON) | Type | |
|---|---|---|
confirm | string |
GET /v1/admin/audit
The access log, newest first: who called what, how they signed in, from which agent.
- Who: server admins
- CLI:
fontego admin audit
| Query | Type | |
|---|---|---|
user | string | |
workspace | string | |
since | string | |
limit | string |
GET /v1/admin/audit/changes
The change log, newest first: who wrote each commit, how they had signed in, from which agent.
- Who: server admins
- CLI:
fontego admin audit changes
| Query | Type | |
|---|---|---|
user | string | |
workspace | string | |
since | string | |
limit | string |