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.

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.

By default a share grants read-only (r) access — recipients can view the visual but not change it. To grant more, append a final ~-segment listing the permission letters you want (r, w, d):

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

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.

Next
Groups