Sharing

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

AI-assisted, human-approvednovem 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.

Note: Use access is not a confidentiality boundary around the values a visualisation displays. Browser rendering sends the viewer the data and configuration needed to draw the result, and variable references may fall back to their rendered text. The raw data, CSV/XLSX, configuration and variable-JSON routes still require r; grant x when seeing and using the rendered result is acceptable, even if downloading its source is not.

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

Seeing who can actually access it

The shared/ listing shows the grants you wrote. It does not show what they come to: a group share is one entry and however many members that group has, and what each member may do is your permission letters narrowed by their role in the group. access/ answers the resolved question — one entry per user who can reach the resource.

GET /v1/users/<you>/vis/plots/en_letter_frequency/access

It is owner-only. Anyone else gets 404, including people the resource is shared with — expanding a group share would name its members to a peer.

Not to be confused with a job's config/access, which names the claim a job's run credential is minted on. This one answers who can reach the resource.

[{"name": "public",
  "target": null,
  "permissions": ["x"],
  "access": ["execute", "info"],
  "via": ["public"],
  "type": "file"},
 {"name": "@jones~rwx",
  "target": "/v1/users/jones",
  "permissions": ["r", "w", "x"],
  "access": ["read", "info", "write", "execute"],
  "via": ["@jones", "@smith~analysts"],
  "type": "link"}]

access is what the user may do, not the letters some share carries: read the source, info to see that it exists, write, execute to use or render it, delete. Letters cannot answer this on their own — x means "may execute" on a job and "may view the render" on a plot, and a d you granted a group buys its members nothing unless their role carries deletion.

On a user entry, permissions and the ~rwx on the name are both access written back as letters, so neither is the share's own bits. That means they are not always what you granted: a group you shared ~rwd with reads ~rwx for a member, losing the d their role does not carry and gaining the x that reading a plot implies. info spells no letter, so an entry holding only that has an empty permissions and a bare name — which is the true answer, not a missing one.

The public entry is the exception: its permissions is the grant itself, so you can revoke it at shared/public. Its two fields can therefore disagree — public~r on a plot is ["r"] granted and read, info, execute conferred, because reading a plot reaches its render.

via names the shares the access came through, spelled as the shared/ listing spells them. owner appears there for you. The actions field is the dir-listing convention every novem listing carries — the HTTP verbs you may use on the entry — and has nothing to do with access.

The public entry is never expanded into users — it grants everyone the same thing rather than anyone anything in particular. It keeps its letters, since those are a grant you can revoke, and carries the actions they confer beside them. A user's entry covers only what their own shares give them; whatever the public entry adds on top applies to them as it does to everyone.

What the listing states is the ceiling a user's tokens can reach. A token of theirs scoped to a claim may get less, and individual leaves under the resource have their own tiers — data and config want read where the rendered result only wants execute.

Note: The dashboard shows the same answer without the API call. Click the Public / Shared / Private badge beside a resource's title and pick Who can access this?; the same entry sits at the bottom of the Access menu in the sidebar. The GraphQL API carries it as the access and publicAccess fields on every resource type, under the same owner-only rule.

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