API
This document gives a basic introduction to the structure and design of the novem api.
AI assisted, human approved — novem uses AI to review and keep our documentation up to date.
The novem API resembles a regular hierarchical file system: folders that
contain files or other folders. You interact with it over HTTP much like you
would a local filesystem: GET to read a file or list a folder, PUT to
create one, POST to write a file's content, and DELETE to remove it. Each
endpoint also carries unix-style read, write and delete permissions, surfaced
in folder listings and via the OPTIONS verb.
The API is located at https://api.novem.io/v1/. For the rest of this document
we use the shorthand / to mean the base of the API, so that e.g. /whoami
corresponds to https://api.novem.io/v1/whoami. Most paths expect plain text
(text/plain). Resources live under a handful of top-level segments: /vis
for your plots, mails, docs and grids, /code for jobs and repos, and /admin
for your profile, groups and settings.
When you create a folder its underlying structure is already populated: creating
a plot under /vis/plots, for example, automatically creates the folder beneath
it with files such as data, url and shortname and folders such as config
and shared.
A GET on a folder returns its contents as a list of JSON objects, where name
is the resource, uri its path, permissions the "file" permissions and
actions the valid HTTP verbs. A GET on a file returns the file's content
directly.
PUT creates folders: PUT /v1/vis/plots/en_letter_freq creates a new plot
named en_letter_freq. These names may only contain lowercase alphanumeric
characters and underscores. PUT is only ever used to create new files and
folders, never to update ones that already exist.
POST writes or updates the content of a file. To turn the plot above into a
bar chart you POST bar to /vis/plots/en_letter_freq/config/type.
When you no longer need the plot, DELETE /v1/vis/plots/en_letter_freq removes
it.
All novem visualisation rendering happens on our servers, and the output is made
available in many formats. The easiest is to view it online by following the url
found under the url endpoint in the root of every visualisation folder. We
also provide pre-rendered output under each visualisation's files/ folder,
where png, pdf, txt and ansi versions are available.
Every visual also carries a globally-unique shortname for addressing it without its owner prefix; this is what the public share links and render aliases are keyed on.
Novem visuals are private to their owner by default, but can be shared with
other users, groups and the world. The shared/ folder holds one entry per
target you share with:
@smith~plots— shared with theplotsgroup created by the usersmith.+company~plots— shared with theplotsgroup created by the organisationcompany.public— shared with the world.
To remove access, DELETE the corresponding entry in shared/. The
sharing reference covers the full mechanism,
including how to grant write access and how to read content shared with you.
- Terminology — the FQNP, shortnames and public read aliases. Tags, Social, Slicing, Vars and Files round out the API reference.
- Novem Markdown — the content format.