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
    ├── @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~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/@smith~analysts
PUT /v1/code/repos/data_fetcher/shared/@smith~analysts

Note: You can only share with a group, never with an individual user or a whole organisation. A bare @username or +orgname target is rejected with a 403. 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 third ~-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

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

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.

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