Files

Overview

Novem is heavily inspired by the unix philosophy of "everything is a file". As such our API is implemented as a hierarchical file system.

As part of this we wanted to make sure that these virtual files supported sensible extension and content expectations. This document provides a short overview of the kind of files you can expect to find in the novem API and how to interact with them.

Inputs

All of our interactions are performed by standard HTTP verbs over HTTPS. If an operation requires submitting data, this is done by providing utf-8 encoded plain text as the body of the post request.

There are a few exceptions, such a registering user accounts, but those are marked as system_dir and system_file and can safely be ignored when interacting with the API.

Value spaces

You always write a plain-text body. The value space (what counts as a valid value) depends on the node. Each writable file is one of a few kinds:

• Text — free-form text: display names, summaries, descriptions, and similar fields. Some text fields are normalised on write (leading and trailing whitespace trimmed, zero-width and directional Unicode characters stripped) so a pasted value behaves predictably. How a text value is rendered varies. See Markup below.

• Boolean — a yes/no toggle. The accepted true values are yes, y, yeah, yup, true, t, ok, ye and on; the false values are no, n, nope, false, f and off (all case-insensitive). Anything the API doesn't recognise is treated as false (and logged), so prefer a plain yes or no.

• Option — one value from a fixed set. A value outside the set is rejected, and the existing value is left unchanged. The valid set is listed on the node's own reference page. Notification settings, for example, accept ignore, info, or important.

• Structural — a few folders interpret the path rather than a body: shared/:group takes a share target (public, @user~group, +org~group), tags/:tag takes a tag name, and a var carries a typed value with its own type/format fields.

Configuration values

A visualisation's config/* keys behave differently from the API-validated options above. They're stored verbatim as text and interpreted later by the rendering pipeline, which falls back to a sensible default for a value it doesn't understand rather than rejecting the write. A typo in config/type therefore yields the default render, not an error. The recognised set for each key lives on the per-product config reference (e.g. plot config, grid layout).

A handful of value vocabularies recur across those keys:

• Colors — a novem theme color name (gray-300, ok, bad, warn), one of the tab10/tab20 palette slots, an XKCD color name, or a #rrggbb hex code. Many color keys also accept a leading * to mean "every series", e.g. * gray-300. See theme colors.
• Sizes — a percentage (40) or an explicit pixel value (120px).
• Booleans / enums — the same yes/no and fixed-set conventions as above, but coerced-to-default rather than rejected.

Markup

Most text is shown verbatim. A few fields are rendered, at one of three levels. The level is fixed per field:

• Plain — names, summaries, ids, var values and most config values are shown as-is, never interpreted.
• Description markdown — resource description fields and plot/grid commentary go through a medium markdown dialect: inline formatting (bold, italic, code, strikethrough, superscript), fenced code blocks, simple tables, KaTeX math and variable embeds. Raw HTML in the source is escaped, not rendered.
• Full novem markdown — the body of documents and e-mails is the complete novem markdown dialect: sections, layout, visualisations and the rest, documented under markdown.

Rendered HTML is sanitised before it is served. Scripts, event handlers, and unknown tags are stripped, and URLs are limited to http, https, mailto, and data. The one place you supply HTML directly is a render header title or footer footnote. These accept a small inline subset (img, b, strong, i, em, span, br); put any CSS in config/render/styles instead.

Size limits

Each writable file has a maximum size, enforced on the POST/PUT body. The limit is measured in characters (Unicode code points), not bytes — content with multi-byte (non-ASCII) characters reaches the cap with fewer bytes. An oversized write is rejected with a 413 response (Request is too large. This endpoint only supports up to N characters) and nothing is stored.

Most other control files (names, descriptions, config flags) carry small limits of their own, in the hundreds to low thousands of characters. A job's rendered result is capped separately at 100 MB — see the jobs guide.

Output

Output formats can vary a bit more than the plain text of the input, but mostly you'll encounter either json for visualisations or dir entries, or plain text for control and data files.

The output of visualisations can be presented in more ways than viewing the web presentations or the e-mails, so we also provide a collection of special purpose output formats, like PDF or a pre-rendered image.

Their outputs are accessible in two different ways, either by appending the corresponding extension to the canonical url of our charts or by accessing the file in the individual visualisations /files folder.

Formats

Different visualisations support different output formats, both depending on the type of visualisation (mail, plot, grid, doc) and the individual subtypes (table plot vs line plot).

If you're curious what types are available you can always list the content of the /files folder of the visual, but we've provided a rough overview below as well. Further details are also documented under the sections for the different visualisation type.

Portable Document Format pdf

The Portable Document Format, or PDF, developed by Adobe in the '90s is the current gold standard in document sharing. Mostly because it always looks the same and prints pretty well.

Many users still prefer to print documents for meetings, analysis and offline reading, and PDF is the go-to format for these use cases.

It was important to us that our documents would look good when printing, so we've created a separate rendering pipeline for our PDF documents to make sure we get the best experience.

You can control several aspects of the pdf rendering process under the /config/render endpoint for the relevant visuals.

Portable Network Graphics png

While PDF is the gold standard for documents, PNG is an excellent format for digitally rendered images. Although the customization options for PNG files are not as extensive as those for PDF files, our visuals also provide PNG versions of their output for convenient use in digital environments.

American National Standards Institute Escape Codes ansi

Whilst novem was initially intended to let you create web visualisations from the command line, the advent of cool services such as wttr.in inspired us to try and create an ascii art version as well.

If you try to curl <url> of any of our visuals that support an ansi output you should receive the ansi version instead. You can also add the .ansi extension to be explicit.

The ansi version uses 256-color ansi escape codes and utf-8 box drawing characters. To see if your current terminal and font supports it. try curl -L novem.io/terminal.

Text txt

The text version is a simplified version the above ansi output, but without colors.