API

Overview

Documents follow the same filesystem conventions as the rest of the novem API: folders, files, HTTP verbs, and the r/w/d permission model. If you haven't already, read the API overview first. This page covers what's specific to the document resource.

Your own documents live under /v1/vis/docs/, and documents shared with you are reachable under /v1/users/:user/vis/docs/. The structure beneath a document is identical on both:

quarterly_report          => Document name
├── assets                => Per-document images and fonts
│   └── <asset>
├── config
│   ├── comments          => Enable/disable comment threads (true/false)
│   ├── custom
│   │   └── custom.css    => Custom CSS overrides
│   ├── theme             => Theme name (default: novem)
│   ├── title             => Reserved
│   ├── toc               => Reserved
│   └── type              => Layout: doc, pres or blog
├── content               => Document content (novem markdown)
├── description           => Description (meta)
├── files                 => Pre-rendered outputs
│   ├── doc.pdf
│   └── doc.pptx
├── log                   => Processing/render log (read-only)
├── name                  => Display name (meta)
├── notifications         => Your notification level for this doc
├── shared                => Sharing entries
├── shortname             => Unique shortname (read-only)
├── summary               => Short text summary (meta)
├── tags                  => Tags on this document
├── threads               => Comment threads
├── url                   => Canonical url (read-only)
└── vars                  => Document variables

Managing documents

Document names must be lowercase alphanumeric with optional underscores, like all novem resource names.

Rename and copy

PATCH accepts either a plain-text body containing the new name, or a JSON body that can additionally request a copy:

# rename
curl -X PATCH https://api.novem.io/v1/vis/docs/quarterly_report \
  -H "Authorization: Bearer $NOVEM_TOKEN" \
  -d "annual_report"

# copy instead of rename
curl -X PATCH https://api.novem.io/v1/vis/docs/quarterly_report \
  -H "Authorization: Bearer $NOVEM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "report_copy", "copy": true}'

A copy clones the content, configuration, and your tags, and gets a fresh shortname. Sharing entries are intentionally not copied. The new document starts out private.

Content and metadata

Writable files take a POST with a text/plain body; DELETE clears them. The content body has a generous size cap; see Size limits.

Configuration

All keys live under config/ and are written with POST (plain text):

See the documents guide for what each type looks like in practice.

Assets

Documents can carry their own images and fonts for use in the content and custom CSS. Assets live under assets/ and are uploaded with the raw file as the request body:

curl -X POST https://api.novem.io/v1/vis/docs/quarterly_report/assets/logo.png \
  -H "Authorization: Bearer $NOVEM_TOKEN" \
  -H "Content-Type: image/png" \
  --data-binary @logo.png

Constraints:

• Content types — image/png, image/jpeg, image/gif, image/svg+xml, image/webp, font/woff, font/woff2, font/ttf, font/otf. The Content-Type header must match.
• Size — at most 5 MiB per asset.
• Names — lowercase alphanumeric with - separators and an optional extension ([a-z0-9][a-z0-9-]*(\.[a-z0-9]+)?), max 64 characters.

Assets on a public document are served publicly. Assets on private or shared documents require the same access as the document itself.

Output formats

Pre-rendered outputs are available under files/:

See files for the general story on novem output formats.

Sharing

Documents are private by default. The shared/ folder controls who can see them:

# share with everyone (requires a public novem profile)
curl -X PUT https://api.novem.io/v1/vis/docs/quarterly_report/shared/public \
  -H "Authorization: Bearer $NOVEM_TOKEN"

# share with one of your groups
curl -X PUT "https://api.novem.io/v1/vis/docs/quarterly_report/shared/@username~research" \
  -H "Authorization: Bearer $NOVEM_TOKEN"

# share with an org group
curl -X PUT "https://api.novem.io/v1/vis/docs/quarterly_report/shared/+acme~analytics" \
  -H "Authorization: Bearer $NOVEM_TOKEN"

GET shared lists current entries, DELETE shared/<entry> revokes access. Sharing with public requires your novem profile itself to be public; private accounts cannot publish content to the world.

Notifications

The notifications file holds your notification preference for this document. It is per-user, not part of the document itself. Valid values are ignore, info, and important; reading it returns the current level (info when no override is set).

Tags, vars and threads

• tags — tag the document with PUT tags/:tag, remove with DELETE. See tags.
• vars — attach live variables (value, type, format, about, threshold) that can be referenced from content as {/u/user/d/doc/v/varname}. See vars.
• threads — the comment threads attached to the document. GET threads lists topics. The config/comments toggle controls whether commenting is enabled.

Read-only alias: /v1/u/:user/d

For quick read access, every document is also reachable through the short FQNP-style alias. These endpoints are GET-only and respect the same access rules as the full API (public documents need no authentication):