Files

Overview

The novem API organises resources as folders and files. Configuration and content paths accept writes, while files/ provides rendered downloads.

Inputs

Most content and configuration writes use a UTF-8 text/plain request body. Some endpoints accept other formats, including JSON for authentication and binary data for assets and space files. Use the content type documented for the endpoint.

Value spaces

For plain-text control files, the value space defines the accepted values:

• 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.

Scalar controls are safe to edit as ordinary text files: the API removes the complete trailing line-ending sequence (including LF and CRLF) before it validates or stores a text, boolean, or option value. Content-bearing files, such as documents, code, CSS, and plot data, preserve their body, including a final newline.

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 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, including blocks, layout, and visualisations, 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 — multi-byte characters use more bytes per character without reducing the character limit. 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.

Resetting files and retained history

DELETE on a versioned content or configuration file resets its current value to the endpoint's default and keeps its previous revisions. Readers with access to the asset can retrieve those revisions with X-History, including after the asset is shared or made public. A reset does not scrub a credential or other sensitive value from history.

There is currently no per-file history purge. Deleting the parent asset removes its file history. Non-versioned secret fields, such as cookie jars, are fully deleted when reset. When a default is unset, its recorded reset revision is empty text; restoring that revision writes an empty value.

Output

Resource and directory listings return JSON; content and configuration files usually return plain text. Visualisations also provide rendered downloads. Read the resource's files/ folder to list its supported formats, or append a supported extension to its web URL.

Formats

Available formats depend on the resource and plot type. The following sections describe the common outputs; the resource's files/ listing is authoritative.

Portable Document Format pdf

PDF preserves the rendered page layout for viewing and printing. Rendering options are available under the resource's config/render path.

PowerPoint pptx

Plots, grids, documents and mails can expose a PowerPoint file in their files/ folder. Document exports create one slide per physical page and keep text and ordinary chart elements editable where possible. Dense or composited content may be rasterised to preserve fidelity.

Document doc.pptx routes accept a one-based ?page=N. They also accept ?type=png|pdf|pptx; PNG requires a selected page. See the document API reference.

Excel workbook xlsx

Supported plots expose files/data.xlsx, a workbook containing one typed worksheet named data. Numbers, booleans, dates and text are written as sheet values rather than flattened display strings. Plot types that cannot export a table answer 415, just like their data.csv route.

Portable Network Graphics png

PNG provides a raster image of the rendered visualisation for use in webpages, presentations, or other applications.

ANSI terminal output ansi

ANSI output uses 256-colour escape codes and UTF-8 box-drawing characters. For a resource that supports it, append .ansi to the web URL. Requests from curl also select ANSI output when available.

To check your terminal's support, run:

curl -L https://novem.io/terminal

Text txt

Text output presents the data without ANSI colour codes.