API

Everything the web app does goes through a REST API under /api/v1. Its OpenAPI description is at /doc, with a page to try calls in the browser, and as JSON at /doc-json, to generate a client from.

curl http://127.0.0.1:3333/api/v1/documents?q=bracket

Who's calling

Until there's sign-in, the caller is named by the X-User header, or is DEV_USER without one. With NODE_ENV=production the header is ignored. See Users and sign-in.

Requests

JSON in, JSON out. Files are uploaded as the raw request body, with the file's name in X-File-Name:

curl -X POST "http://127.0.0.1:3333/api/v1/versions/$DRAFT/artifacts?kind=part-source" \
  -H "X-File-Name: bracket.ofb" -H "Content-Type: application/octet-stream" \
  --data-binary @bracket.ofb

Conflicts

What can change has a version, sent as ETag. Send it back as If-Match and a change based on an older state is refused with 412 instead of overwriting someone else's. The web app does this for every upload.

Status	Means
400	Something's wrong with the request, said in the message
404	No such thing
409	Not now: someone else has reserved the branch, a release rule isn't met, the draft is still being processed
412	Your If-Match is out of date

The routes

Documents and folders · Branches and versions · Files and references · Jobs and workers · Code and runs