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 and w for mutation. Deletion cannot be shared: only the owner deletes, and a share asking for d is refused with 400. 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 access it

The shared/ listing shows the shares you created. The access/ listing resolves those shares into effective access for each user, taking group membership and roles into account.

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

Only the owner can read this listing. Other callers receive 404. This path is separate from a job's config/access, which controls the credential used during a run.

[{"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"}]

Each user entry contains:

access: effective capabilities, such as read, info, write, execute, and delete.
permissions and the name's permission suffix: those capabilities expressed as letters, after applying role restrictions. They may differ from the original share. For example, a group share of ~r on a plot becomes ~rx, because reading a plot also permits rendering it. info has no letter, so an entry with only info has an empty permissions list.
via: the share entries that granted access. Your own entry includes owner.
actions: HTTP verbs available on the listing entry, separate from the resource capabilities in access.

The public entry retains the granted permission letters so that you can identify and revoke the share. Its access field also includes implied capabilities: public r on a plot grants read, info, and execute. Public access is listed separately and is not expanded into user entries. It applies in addition to each user's individual access.

This listing describes the maximum access available to a user. A scoped token can restrict it further. Individual resource paths also require specific capabilities: source data needs read, while rendered output needs 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 shared resources

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

Conversations