API

Sharing

This document shows you how to share your visualisations with other users as well as accessing documents shared with you.

AI assisted, human approved — novem uses AI to review and keep our documentation up to date.

Overview

Novem resources are private to their owner by default. To let other people see one, you share it by creating an entry in its shared/ folder — one entry per target you share with. This works the same for visualisations (plots, grids, docs, mails) and code resources (repos and jobs).

en_letter_frequency
└── shared
    ├── @jones               => the user jones, directly
    ├── @smith~analysts      => analysts user group owned by smith
    ├── +acme~research       => research group in the acme org
    └── public               => shared with everyone

You add a share by PUTting the target as a file under the visual's shared/ folder. The leaf name encodes who you are sharing with:

@username — a user, directly. The user must be visible to you: public, connected to you, or in a group with you.
@username~group — a user group: the group created by username. You must be a member of that group.
+orgname~group — an org group: the group belonging to the organisation orgname.
public — the world. Your own account must be public to share publicly.

PUT /v1/vis/plots/en_letter_frequency/shared/@jones
PUT /v1/vis/plots/en_letter_frequency/shared/@smith~analysts
PUT /v1/code/repos/data_fetcher/shared/@jones

A direct share is private to the two of you: only you and the target user ever see that entry in the share listing. The target is notified when the share is created.

Note: You cannot share with a whole organisation; a bare +orgname target is rejected with a 403. For a broader audience than one user, create a user group (@you~group), add the people you want, then share with that group.

Choosing permissions

Bare public, user and group shares grant use (x) access. Recipients can view plots, grids, docs and emails, or use repos and jobs, without reading source. Add r for source data and configuration; w and d grant mutation and deletion independently. Append the desired letters after ~:

PUT /v1/vis/plots/en_letter_frequency/shared/public~x
PUT /v1/vis/plots/en_letter_frequency/shared/public~r

For visualisations, r includes viewing the rendered result. For jobs and repos, r and x are independent: r allows source reads, x allows running jobs or using a repo as a job step or module plot, and rx allows both. This applies to public, direct and group shares. Public execution requires a logged-in caller and respects token restrictions. Public cannot grant w or d. For spaces, images, computers, views, TVs and runners, request public r explicitly; public x is unsupported.

Clients that publish and then download source data must request public r.

-- let the analysts group read and write
PUT /v1/vis/plots/en_letter_frequency/shared/@smith~analysts~rw
-- let jones read and write
PUT /v1/vis/plots/en_letter_frequency/shared/@jones~rw

Re-sharing the same target with different permissions updates the existing share; re-sharing with the same permissions is a no-op.

Note: In the two-segment @ form, a second segment made up only of permission letters (r, w, d, x) always reads as permissions for a direct share. Permission-string names are therefore reserved: creating a user group named like one (say rw) is rejected.

To revoke access, DELETE the corresponding entry from the shared/ folder:

DELETE /v1/vis/plots/en_letter_frequency/shared/@smith~analysts

Accessing things shared with you

Resources shared with a group you belong to appear under that group's shared/ tree, organised by kind:

/v1/users/<owner>/groups/<group>/shared
├── vis
│   ├── plots            => @<sharer>~<plot> entries
│   ├── grids
│   ├── docs
│   └── mails
└── code
    ├── repos            => @<sharer>~<repo> entries
    └── jobs

Each leaf lists one entry per shared resource, named @<sharer>~<name>. You can also access a shared resource directly at its canonical path (e.g. GET /v1/users/<owner>/code/repos/<repo>/branches) — browse it just like your own, subject to the permissions the owner granted.

Resources shared with you directly have no group tree; access them at their canonical path. The resource's shared/ listing shows your own @you~<perms> entry, which is how a client can tell what you are allowed to do with it.

Note: A leaf returns 404 while nothing of that kind is shared with the group — an empty shared/vis/plots is indistinguishable from a missing one.

Files

Groups