hot.dev/box / ::box::sharing

Sharing: shared links on files and folders (PUT ... {shared_link}), resolving a shared link to its item, and collaborations (invite a user or group to a file or folder, list, update, remove).

item-type is "file" or "folder" throughout.

Plans. company shared-link access and some roles need a paid plan; enterprises can restrict shared links and external collaboration, in which case Box answers 403.

Values

COLLAB_LOCAL_KEYS

COLLAB_LOCAL_KEYS: Vec [
  "is-access-only",
  "can-view-path",
  "expires-at"
]

ITEM_TYPES

ITEM_TYPES: Vec [
  "file",
  "folder"
]

ROLES

ROLES: Vec [
  "editor",
  "viewer",
  "previewer",
  "uploader",
  "previewer uploader",
  "viewer uploader",
  "co-owner",
  "owner"
]

SETTING_KEYS

SETTING_KEYS: Vec [
  "access",
  "password",
  "vanity-name",
  "unshared-at",
  "can-download",
  "can-preview",
  "can-edit"
]

Functions

add-collaboration

fn (item-type: Str, item-id: Str, accessible-by: Map, role: Str): Map
fn (item-type: Str, item-id: Str, accessible-by: Map, role: Str, opts: Map): Map

POST /collaborations - give a user or group a role on a file or folder. opts.notify: true emails the invitee. Returns the collaboration (id, status accepted or pending, role, ...).

collab ::box::sharing/add-collaboration("folder", "12345", ::box::sharing/user-by-email("ana@example.com"), "viewer", {notify: false})
collab.id

boxapi-header

fn (shared-link: Str, password: Str?): Str

The BoxApi header value for shared-link access (pure): shared_link=<url> plus &shared_link_password=<pw> when a password is given, in the raw form Box documents (no URL encoding).

collaboration-body

fn (item-type: Str, item-id: Str, accessible-by: Map, role: Str, opts: Map): Map

The POST /collaborations body (pure): item: {type, id}, accessible_by (see user-by-email / user-by-id / group-by-id), role (editor, viewer, previewer, uploader, previewer uploader, viewer uploader, co-owner), plus optional is-access-only, can-view-path (folders), expires-at (RFC 3339).

get-shared-item

fn (shared-link: Str): Map
fn (shared-link: Str, password: Str?): Map
fn (shared-link: Str, password: Str?, opts: Map): Map

GET /shared_items - the file or folder behind a shared link (any Box user's link, not only your own). Pass the password for protected links. The returned id works with the other functions when you add {boxapi: ::box::sharing/boxapi-header(link, password)} to their opts.

get-shared-link

fn (item-type: Str, item-id: Str): Map?
fn (item-type: Str, item-id: Str, opts: Map): Map?

The item's shared_link (null when it has none).

group-by-id

fn (group-id: Str): Map

An accessible_by for a Box group id (pure).

item-path

fn (item-type: Str, item-id: Str): Str

/files/{id} or /folders/{id} for an item type (pure), or an Err for any other type.

list-all-collaborations

fn (item-type: Str, item-id: Str): Vec
fn (item-type: Str, item-id: Str, opts: Map): Vec

Every collaboration on an item (all marker pages).

list-collaborations

fn (item-type: Str, item-id: Str): Map
fn (item-type: Str, item-id: Str, opts: Map): Map

GET /files/{id}/collaborations (or /folders/{id}/collaborations) - one page of an item's collaborations (marker paging: {entries, next_marker}; limit up to 1000). Pending invites are included.

remove-collaboration

fn (collaboration-id: Str): Bool
fn (collaboration-id: Str, opts: Map): Bool

DELETE /collaborations/{id} - remove a collaboration. Returns true.

remove-shared-link

fn (item-type: Str, item-id: Str): Map
fn (item-type: Str, item-id: Str, opts: Map): Map

Remove an item's shared link. This is the one place box sends a JSON null on purpose: Box removes a link with {"shared_link": null}. Returns the item.

set-shared-link

fn (item-type: Str, item-id: Str): Map
fn (item-type: Str, item-id: Str, opts: Map): Map

PUT /files/{id} (or /folders/{id}) with shared_link - create or update an item's shared link. Returns the item with its shared_link (url, download_url, access, effective_access, permissions, ...).

item ::box::sharing/set-shared-link("file", "12345", {access: "open", can-download: true, unshared-at: "2026-12-31T00:00:00Z"})
item.shared_link.url

shared-link-settings

fn (opts: Map): Map

The shared_link object for set-shared-link (pure), from Hot-style keys: access ("open", "company", "collaborators"; omitted for the enterprise default), password (open links only; at least 8 characters with a number, capital or symbol), vanity-name, unshared-at (RFC 3339 expiry), can-download, can-preview, can-edit (Bools). Unset keys are omitted.

update-collaboration

fn (collaboration-id: Str, changes: Map): Map
fn (collaboration-id: Str, changes: Map, opts: Map): Map

PUT /collaborations/{id} - change role, status (accepted / rejected for pending invites), expires_at or can_view_path. Null values are dropped.

user-by-email

fn (email: Str): Map

An accessible_by for a user by email (pure). Box invites addresses that have no Box account yet.

user-by-id

fn (user-id: Str): Map

An accessible_by for a Box user id (pure).