API
Every endpoint under a novem grid: lifecycle, content, configuration, outputs, variables and sharing.
AI assisted, human approved — novem uses AI to review and keep our documentation up to date.
Grids follow the same conventions as the rest of the novem API: the
filesystem metaphor, the HTTP verbs, plain-text writes, and the r/w/d
permission model. See the API overview for the general
mechanics. This page lists what's specific to grids.
Every path below also answers OPTIONS with the verbs valid for your token.
A grid lives at three equivalent addresses:
| Path | Use |
|---|---|
/v1/vis/grids/:grid | Your own grids (shorthand for your username) |
/v1/users/:user/vis/grids/:grid | Any user's grids, yours or ones shared with you |
/v1/u/:user/g/:grid | Read-only FQNP alias with JSON info and renders |
The first two serve the same tree. When you address another user's grid, your
access is decided by its shares: reads need a share granting r, writes w,
deletes d. The examples below use the /vis/grids form.
| Verb | Path | Description |
|---|---|---|
GET | /vis/grids | List your grids |
PUT | /vis/grids/:grid | Create a grid — ids are lowercase alphanumerics plus - and _ (not leading) |
GET | /vis/grids/:grid | List the grid's files and folders |
PATCH | /vis/grids/:grid | Rename — body is the new id (text/plain), or {"name": "...", "copy": true} (application/json) to copy instead |
DELETE | /vis/grids/:grid | Delete the grid |
The two files that define the dashboard itself. See the layout reference for their grammar:
| Verb | Path | Description |
|---|---|---|
POST / GET / DELETE | /vis/grids/:grid/layout | The box drawing of the dashboard |
POST / GET / DELETE | /vis/grids/:grid/mapping | Binds layout labels to plots |
DELETE on a file endpoint truncates it (clears the content) rather than
removing the path. Both files are capped. See
Size limits.
| Verb | Path | Description |
|---|---|---|
POST / GET / DELETE | /vis/grids/:grid/name | Display name |
POST / GET / DELETE | /vis/grids/:grid/summary | One-line summary |
POST / GET / DELETE | /vis/grids/:grid/description | Longer description, rendered as markdown |
GET | /vis/grids/:grid/shortname | The grid's unique short id |
GET | /vis/grids/:grid/url | Canonical url (https://novem.io/g/<shortname>) |
GET | /vis/grids/:grid/log | Processing log |
POST / GET | /vis/grids/:grid/notifications | Your notification preference for this grid: ignore, info (default) or important |
All config keys are plain-text files supporting POST (write), GET (read)
and DELETE (reset to default). GET on config and its sub-folders lists
the keys.
| Path | Default | Description |
|---|---|---|
config/type | dashboard | Rendering mode: dashboard, landscape, portrait or stretch (aliases like ls, pt, fs, dash accepted) |
config/theme | novem | Color theme |
config/comments | true | Set to false to block new comment threads on the grid |
config/borders/style | thin | Panel border style |
config/borders/corner | square | Panel corner style |
config/borders/color | * gray-300 | Panel border color |
config/borders/label | (empty) | Panel border label |
config/colors/theme | #fffff | Frame color theme |
The config/render folder adds a header and footer band around the dashboard
and lets you style them. These endpoints require a premium or
enterprise subscription:
| Path | Description |
|---|---|
config/render/header/title | Dashboard title — falls back to the grid's name when unset |
config/render/footer/footnote | Footer text |
config/render/footer/pagenum | Page-number setting for paged output |
config/render/styles | Custom CSS injected into the render (e.g. @font-face rules for the title and footer) |
title and footnote accept a sanitised subset of HTML: img, b,
strong, i, em, span, and br. Anything else, including <style>
tags, is stripped. Put CSS in config/render/styles instead.
Pre-rendered outputs live under files/, and the machine-readable state under
json/:
| Path | Description |
|---|---|
files/grid.png | Image render — accepts a ?s= size parameter |
files/grid.pdf | PDF render |
files/grid.pptx | PowerPoint render |
files/grid.ansi | Terminal render (256-color ansi) |
files/grid.txt | Plain-text render |
json/config.json | The resolved configuration |
json/data.json | The parsed layout structure |
json/meta_data.json | The parsed mapping refs |
See files for more on the output formats.
Grids support novem vars, live values you can reference from comments, mails and docs:
| Verb | Path | Description |
|---|---|---|
GET | /vis/grids/:grid/vars | List the grid's vars |
PUT / GET / DELETE | /vis/grids/:grid/vars/:var | Create, inspect or remove a var |
POST / GET / DELETE | .../vars/:var/value | The var's value |
POST / GET / DELETE | .../vars/:var/type | relative (default), number, date or text |
POST / GET / DELETE | .../vars/:var/format | Format string (default +,.2%) |
POST / GET / DELETE | .../vars/:var/threshold | Threshold for relative vars (default 0) |
POST / GET / DELETE | .../vars/:var/about | Short description |
GET | .../vars/:var/out.txt | The formatted value, plain text |
GET | .../vars/:var/out.ansi | The formatted value, ansi |
| Verb | Path | Description |
|---|---|---|
GET | /vis/grids/:grid/shared | List who the grid is shared with |
PUT / DELETE | /vis/grids/:grid/shared/:group | Add or remove a share: public, @user~group or +org~group |
GET | /vis/grids/:grid/tags | List the grid's tags |
PUT / DELETE | /vis/grids/:grid/tags/:tag | Tag or untag the grid |
GET | /vis/grids/:grid/threads | List comment-thread topics |
GET / PUT / POST / DELETE | /vis/grids/:grid/threads/* | Read and write topics, comments and reactions |
Note: creating, updating or deleting threads, comments and reactions
requires a paid subscription (basic and up). Reading threads is available
on all plans, and the owner can turn comments off entirely via
config/comments.
The /v1/u/:user/g tree is the read-oriented alias used for embedding and
quick inspection. It serves JSON and renders directly, without the
filesystem-style navigation:
| Path | Description |
|---|---|
/u/:user/g | JSON list of the user's grids visible to you — id, shortname, name, summary, type, canonical uri, social counts, shares and tags |
/u/:user/g/:grid | The full grid bundle as JSON: parsed structure (data), mapping refs (metadata), resolved config, references, and an about block with urls and social stats |
/u/:user/g/:grid/img | Image render — accepts a ?s= size parameter |
/u/:user/g/:grid/pdf | PDF render |
/u/:user/g/:grid/pptx | PowerPoint render |
/u/:user/g/:grid/ansi | Terminal render — append /html for an HTML wrapping, or /html/img for an image of it |
/u/:user/g/:grid/txt | Plain-text render — same /html and /html/img chaining |
/u/:user/g/:grid/v | The grid's vars as JSON |
/u/:user/g/:grid/v/:var | One var as JSON |
/u/:user/g/:grid/v/:var/txt | The formatted var value, plain text |
/u/:user/g/:grid/v/:var/ansi | The formatted var value, ansi |
Access through the alias follows the same share rules: public grids work without a token, everything else needs a token with read access.
- Layout & mapping — the two grid content files.
- API overview — verbs, permissions and sharing.