Grid

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.

Addressing a grid

A grid lives at three equivalent addresses:

PathUse
/v1/vis/grids/:gridYour own grids (shorthand for your username)
/v1/users/:user/vis/grids/:gridAny user's grids, yours or ones shared with you
/v1/u/:user/g/:gridRead-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.

Lifecycle

VerbPathDescription
GET/vis/gridsList your grids
PUT/vis/grids/:gridCreate a grid — ids are lowercase alphanumerics plus - and _ (not leading)
GET/vis/grids/:gridList the grid's files and folders
PATCH/vis/grids/:gridRename — body is the new id (text/plain), or {"name": "...", "copy": true} (application/json) to copy instead
DELETE/vis/grids/:gridDelete the grid

Content

The two files that define the dashboard itself. See the layout reference for their grammar:

VerbPathDescription
POST / GET / DELETE/vis/grids/:grid/layoutThe box drawing of the dashboard
POST / GET / DELETE/vis/grids/:grid/mappingBinds 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.

Metadata

VerbPathDescription
POST / GET / DELETE/vis/grids/:grid/nameDisplay name
POST / GET / DELETE/vis/grids/:grid/summaryOne-line summary
POST / GET / DELETE/vis/grids/:grid/descriptionLonger description, rendered as markdown
GET/vis/grids/:grid/shortnameThe grid's unique short id
GET/vis/grids/:grid/urlCanonical url (https://novem.io/g/<shortname>)
GET/vis/grids/:grid/logProcessing log
POST / GET/vis/grids/:grid/notificationsYour notification preference for this grid: ignore, info (default) or important

Configuration

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.

PathDefaultDescription
config/typedashboardRendering mode: dashboard, landscape, portrait or stretch (aliases like ls, pt, fs, dash accepted)
config/themenovemColor theme
config/options/commentstrueSet to false to block new comment threads on the grid
config/borders/stylethinPanel border style
config/borders/cornersquarePanel corner style
config/borders/color* gray-300Panel border color
config/borders/label(empty)Panel border label
config/colors/theme#fffffFrame color theme

Render chrome (premium)

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:

PathDescription
config/render/header/titleDashboard title — falls back to the grid's name when unset
config/render/footer/footnoteFooter text
config/render/footer/pagenumPage-number setting for paged output
config/render/stylesCustom 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.

Outputs

Pre-rendered outputs live under files/, and the machine-readable state under json/:

PathDescription
files/grid.pngImage render — accepts a ?s= size parameter
files/grid.pdfPDF render
files/grid.pptxPowerPoint render
files/grid.ansiTerminal render (256-color ansi)
files/grid.txtPlain-text render
json/config.jsonThe resolved configuration
json/data.jsonThe parsed layout structure
json/meta_data.jsonThe parsed mapping refs

See files for more on the output formats.

Variables

Grids support novem vars, live values you can reference from comments, descriptions and document content:

VerbPathDescription
GET/vis/grids/:grid/varsList the grid's vars
PUT / GET / DELETE/vis/grids/:grid/vars/:varCreate, inspect or remove a var
POST / GET / DELETE.../vars/:var/valueThe var's value
POST / GET / DELETE.../vars/:var/typerelative, number (default), date or text
POST / GET / DELETE.../vars/:var/formatFormat string (no default)
POST / GET / DELETE.../vars/:var/thresholdThreshold for relative vars (default 0)
POST / GET / DELETE.../vars/:var/aboutShort description
GET.../vars/:var/out.txtThe formatted value, plain text
GET.../vars/:var/out.ansiThe formatted value, ansi

Sharing, tags and threads

VerbPathDescription
GET/vis/grids/:grid/sharedList who the grid is shared with
PUT / DELETE/vis/grids/:grid/shared/:groupAdd or remove a share: public, @user~group or +org~group
GET/vis/grids/:grid/tagsList the grid's tags
PUT / DELETE/vis/grids/:grid/tags/:tagTag or untag the grid
GET/vis/grids/:grid/threadsList 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/options/comments.

The FQNP alias

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:

PathDescription
/u/:user/gJSON list of the user's grids visible to you — id, shortname, name, summary, type, canonical uri, social counts, shares and tags
/u/:user/g/:gridThe 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/imgImage render — accepts a ?s= size parameter
/u/:user/g/:grid/pdfPDF render
/u/:user/g/:grid/pptxPowerPoint render
/u/:user/g/:grid/ansiTerminal render — append /html for an HTML wrapping, or /html/img for an image of it
/u/:user/g/:grid/txtPlain-text render — same /html and /html/img chaining
/u/:user/g/:grid/vThe grid's vars as JSON
/u/:user/g/:grid/v/:varOne var as JSON
/u/:user/g/:grid/v/:var/txtThe formatted var value, plain text
/u/:user/g/:grid/v/:var/ansiThe 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.

See also

Next
API