Skip to Content
FontegoDocs

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.

GET /v1/instance

What this server is, how long its sessions last, and where its CLI signs in (OAuth endpoints).

Accounts

GET /v1/me

Who you are, and with which token.

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.

Body (JSON)Type
emailstringRequired.

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
passwordstringRequired. at least 15 characters, at most 256 characters.
namestringat 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).

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_idstringRequired.
redirect_uristringRequired.
code_challengestringRequired.
code_challenge_methodstringRequired.
statestringat most 500 characters.
machinestringat most 80 characters.
approvebooleanRequired.

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).

Body (JSON)Type
client_idstringRequired.
machinestringat 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
approvebooleanRequired.

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.

POST /v1/oauth/revoke

Close the session of an access or refresh token (RFC 7009); answers 200 even for unknown tokens.

Workspaces

GET /v1/workspaces

The workspaces you can see, with your role in each.

QueryType
categorystring

POST /v1/workspaces

Create a workspace; whoever creates it becomes its admin.

Body (JSON)Type
slugstringRequired.
namestringat most 200 characters.
descriptionstringat most 5000 characters.
categorystringat most 100 characters.
templatestring
gitstringat most 2000 characters.
branchstringat most 200 characters.
historyboolean

GET /v1/templates

The templates a new workspace can start from.

GET /v1/workspaces/{workspace}

A workspace: description, category, your role and its last change.

PATCH /v1/workspaces/{workspace}

Change a workspace's name, description or category.

Body (JSON)Type
namestringat most 200 characters.
descriptionstringat most 5000 characters.
categorystringat most 100 characters.

GET /v1/workspaces/{workspace}/members

Who is in a workspace, with which role.

PUT /v1/workspaces/{workspace}/members/{email}

Give someone with an account a role in a workspace.

Body (JSON)Type
role`"reader" \"editor" \

DELETE /v1/workspaces/{workspace}/members/{email}

Take someone out of a workspace.

GET /v1/workspaces/{workspace}/paths

The paths a workspace protects (only its admins write them) and rejects (nobody writes them).

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.

DELETE /v1/workspaces/{workspace}/paths/protected/{+pattern}

Stop protecting a path.

PUT /v1/workspaces/{workspace}/paths/rejected/{+pattern}

Reject a path: nobody can write it (server admins only).

DELETE /v1/workspaces/{workspace}/paths/rejected/{+pattern}

Stop rejecting a path (server admins only).

DELETE /v1/workspaces/{workspace}/paths

Go back to the instance's default paths, for both kinds or one (the rejected ones: server admins only).

QueryType
kind`"protected" \"rejected"`

Files

GET /v1/workspaces/{workspace}/tree

The files and folders in a folder (recursive=1 for everything below it).

QueryType
pathstring
revstring
recursivestring

GET /v1/workspaces/{workspace}/files/{+path}

A file's content (meta=1 for its hash, mode and size instead; download=1 to save it).

QueryType
revstring
metastring
downloadstring

GET /v1/workspaces/{workspace}/history

Commits, newest first, of the workspace or of one path.

QueryType
pathstring
revstring
limitstring

GET /v1/workspaces/{workspace}/sync

What changed since a commit, for keeping a copy in step (reset=true: take it as the full tree).

QueryType
sincestring

GET /v1/workspaces/{workspace}/search

Find text in the workspace's files.

QueryType
qstringRequired.
pathstring
limitstring

POST /v1/workspaces/{workspace}/changes

Write: whole files plus the hash each edit started from; text changed on both sides is merged.

Body (JSON)Type
baseCommit`string \null`
messagestringat most 10000 characters, default "".
opsany[]Required.
clientstringat most 40 characters.

GET /v1/workspaces/{workspace}/events

Server-Sent Events: ready, then commit on every change.

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).

Body (JSON)Type
contentstring
contentBase64string
baseHash`string \null`
mode`"100644" \"100755" \
messagestringat 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.

Body (JSON)Type
baseHashstring
messagestringat 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.

Body (JSON)Type
fromstringRequired.
tostringRequired.
baseHashstring
messagestringat most 10000 characters.

Server admin

GET /v1/admin/users

Everyone with an account on this server, and whether they can sign in.

POST /v1/admin/users/invitations

Invite someone: creates their account and mails them a link to set their password (valid 7 days).

Body (JSON)Type
emailstringRequired.
namestringat most 200 characters.
adminboolean

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.

POST /v1/admin/users/{email}/disable

Stop someone from signing in, and close their sessions, CLI logins and agent tokens at once.

POST /v1/admin/users/{email}/enable

Let someone who was disabled sign in again.

POST /v1/admin/users

Create an account without a password, for tokens only (to invite a person, use /users/invitations).

Body (JSON)Type
emailstringRequired.
namestringat most 200 characters.
isAdminboolean

POST /v1/admin/users/{email}/tokens

Create a token for someone, or for their agent.

Body (JSON)Type
labelstringat most 200 characters.
kind`"person" \"agent"`

GET /v1/admin/mail

How this server sends mail: through which SMTP, or not at all.

GET /v1/admin/mail/outbox

Messages that couldn't go out (no SMTP, or sending failed), with the link to pass on by hand.

POST /v1/admin/mail/test

Send a test message, to check the SMTP settings.

Body (JSON)Type
tostringRequired.

GET /v1/admin/settings

The instance's settings: each one's value and where it comes from (the server's config wins).

GET /v1/admin/settings/{key}

One setting: its value, what it is for, and where it comes from.

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.

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.

DELETE /v1/admin/users/{email}

Delete an account at once, with its sessions, tokens and memberships; what it wrote stays in the history.

Body (JSON)Type
confirmbooleanRequired.

PUT /v1/admin/users/{email}/admin

Make someone a server admin.

DELETE /v1/admin/users/{email}/admin

Stop someone being a server admin; the server always keeps one.

POST /v1/admin/users/{email}/password-reset

Send someone a link to set a new password (or get it to pass on, without mail).

GET /v1/admin/sessions

Open sessions (browsers and CLIs) of everyone, or of one person.

QueryType
userstring

DELETE /v1/admin/sessions/{id}

Close someone's session at once.

GET /v1/admin/tokens

Tokens that still work, of everyone or of one person (they don't expire).

QueryType
userstring

DELETE /v1/admin/tokens/{id}

Revoke a token at once.

GET /v1/admin/workspaces

Every workspace, also those you're not a member of and the archived ones, with how many members each has.

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.

DELETE /v1/admin/workspaces/{workspace}/archived

Bring an archived workspace back, as it was.

DELETE /v1/admin/workspaces/{workspace}

Delete an archived workspace for good: its files, its history and its members. Its id, typed again, confirms it.

Body (JSON)Type
confirmstring

GET /v1/admin/audit

The access log, newest first: who called what, how they signed in, from which agent.

QueryType
userstring
workspacestring
sincestring
limitstring

GET /v1/admin/audit/changes

The change log, newest first: who wrote each commit, how they had signed in, from which agent.

QueryType
userstring
workspacestring
sincestring
limitstring

On this page

The serverGET /v1GET /v1/healthGET /v1/commandsGET /v1/instanceAccountsGET /v1/mePOST /v1/password-resetGET /v1/links/{token}POST /v1/links/{token}Sessions and signing inPOST /v1/sessionDELETE /v1/sessionPOST /v1/session/codePOST /v1/oauth/authorizePOST /v1/oauth/deviceGET /v1/oauth/device/{code}POST /v1/oauth/device/{code}POST /v1/oauth/tokenPOST /v1/oauth/revokeWorkspacesGET /v1/workspacesPOST /v1/workspacesGET /v1/templatesGET /v1/workspaces/{workspace}PATCH /v1/workspaces/{workspace}GET /v1/workspaces/{workspace}/membersPUT /v1/workspaces/{workspace}/members/{email}DELETE /v1/workspaces/{workspace}/members/{email}GET /v1/workspaces/{workspace}/pathsPUT /v1/workspaces/{workspace}/paths/protected/{+pattern}DELETE /v1/workspaces/{workspace}/paths/protected/{+pattern}PUT /v1/workspaces/{workspace}/paths/rejected/{+pattern}DELETE /v1/workspaces/{workspace}/paths/rejected/{+pattern}DELETE /v1/workspaces/{workspace}/pathsFilesGET /v1/workspaces/{workspace}/treeGET /v1/workspaces/{workspace}/files/{+path}GET /v1/workspaces/{workspace}/historyGET /v1/workspaces/{workspace}/syncGET /v1/workspaces/{workspace}/searchPOST /v1/workspaces/{workspace}/changesGET /v1/workspaces/{workspace}/eventsPUT /v1/workspaces/{workspace}/files/{+path}DELETE /v1/workspaces/{workspace}/files/{+path}POST /v1/workspaces/{workspace}/moveServer adminGET /v1/admin/usersPOST /v1/admin/users/invitationsPOST /v1/admin/users/{email}/invitationPOST /v1/admin/users/{email}/disablePOST /v1/admin/users/{email}/enablePOST /v1/admin/usersPOST /v1/admin/users/{email}/tokensGET /v1/admin/mailGET /v1/admin/mail/outboxPOST /v1/admin/mail/testGET /v1/admin/settingsGET /v1/admin/settings/{key}PUT /v1/admin/settings/{key}DELETE /v1/admin/settings/{key}DELETE /v1/admin/users/{email}PUT /v1/admin/users/{email}/adminDELETE /v1/admin/users/{email}/adminPOST /v1/admin/users/{email}/password-resetGET /v1/admin/sessionsDELETE /v1/admin/sessions/{id}GET /v1/admin/tokensDELETE /v1/admin/tokens/{id}GET /v1/admin/workspacesPUT /v1/admin/workspaces/{workspace}/archivedDELETE /v1/admin/workspaces/{workspace}/archivedDELETE /v1/admin/workspaces/{workspace}GET /v1/admin/auditGET /v1/admin/audit/changes