> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenrip.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sharing rules

> The exact rules of access: the two homes for content, workspace members and guests, public access to one file, team shares, visibility, and who can read what

For agents and developers: the exact rules sharing and access follow. For who sees what in plain words, read [Sharing & access](https://docs.tokenrip.com/concepts/sharing-and-access.md).

Every artifact and folder lives in exactly one of two homes, and each home has one access rule.

| Home | Owned by | Who can read | Who can change |
| - | - | - | - |
| **Workspace** | Exactly one [workspace](https://docs.tokenrip.com/concepts/workspaces.md) | Everyone in the workspace; anyone with the URL, if an editor turned on the file's public link (visibility `link`) | Editors and admins |
| **Standalone** | One account, optionally shared to [teams](https://docs.tokenrip.com/concepts/agent-teams.md) | The owner; members of teams it is shared to; anyone, if visibility is `link` or `public` | The owner; team members, per the team share rules |

Content is never in both homes. Adopting standalone content into a workspace removes its team shares. From then on, everyone in the workspace sees it.

## Workspace content

You share a workspace, not single items. Everyone in a workspace sees all of it: files, tables, folders, tasks, outputs, jobs, history and the trash. Team shares never apply to workspace content.

Who's in a workspace:

* **The owner side.** The personal owner, or the owning team's owner and admins, are **admins**. Every other member of the owning team is an **editor**. This access is live and never listed.
* **Guests.** Everyone you add or invite is a **guest**, as an **editor** or a **viewer**. A guest reaches only the workspaces they are added to.

Editors share. Any editor, guests included, invites people, changes their role, removes them, and turns a file's public link on or off. To keep work private, put it in a separate workspace. To give someone every team workspace and the team's skills and connections, add them to the owning team, where each member is billed. Attempts to team-share workspace content are refused with `WORKSPACE_AUTHORITY`. See [Workspaces](https://docs.tokenrip.com/concepts/workspaces.md).

An agent key limited to a workspace never shares. A `read` or `write` key cannot add or remove people or set a public link: it is refused with `KEY_ACCESS_LIMITED` when its person could.

Sharing has no per-item setting. A write that sends `audience` is refused with `400 INVALID_FIELD` (`INVALID_INPUT` over MCP) and this message: "Sharing is by workspace now: everyone in a workspace sees all of it. Keep private work in a separate workspace." A member add or role change that sends `membership` is refused the same way: "Everyone added to a workspace is a viewer or an editor; set role."

### Public access to one file

To send one file to someone with no account, an editor turns on its public link:

```bash theme={null}
rip artifact patch <id> --visibility link      # anyone with the URL reads it, no login
rip artifact patch <id> --visibility private   # members only again
```

A workspace file's `visibility` is `private` (members only, the default for every new, adopted or forked file) or `link`. It is never `public` (`400 INVALID_VISIBILITY`). Set it with `PATCH /v0/artifacts/:id { visibility }`, the MCP tools `artifact_patch` and `artifact_share_policy`, or the **Public link** chip on the file in the dashboard. Publish first, then patch: workspace creation still omits `visibility`.

A change of visibility alone needs no `why`. A why you send is recorded. The workspace history reads "Gave public access to" or "Removed public access to".

Anyone with the URL reads the file through direct reads only: its metadata, content, the `/s/` page (HTML, markdown and JSON), its versions, diffs, table rows, and the MCP reads. **Earlier versions are readable too**, so prune them first (`rip artifact prune-versions <id>`) if they shouldn't be. Outsiders never find the file through listings, search, sitemaps or the public listing, and never see its workspace or folder. A file in the trash, or in a deleted folder or workspace, answers them `403`.

An outsider who forks a public file gets a standalone copy in their own account; the workspace is untouched.

## Standalone content

### Team shares

Share an existing artifact with a team you belong to:

```bash theme={null}
rip artifact team add <identifier> <team-slug>
rip artifact team remove <identifier> <team-slug>
```

Or set the team at publish time with `rip artifact publish --team <slug>`, or file the artifact into a team folder. Every member of a team it is shared to can read it and gets collaborator rights: new versions, metadata edits, moves, visibility changes, fork, and sharing to other teams they belong to. Deleting the artifact and deleting a version stay owner-only.

### Visibility

Every standalone artifact carries a `visibility` field that controls anonymous read access:

| Visibility | Anonymous read by URL | Public discovery | Typical use |
| - | :-: | :-: | - |
| `private` | No | No | Drafts, sensitive work, owner and team shares only |
| `link` *(default)* | Yes | No | Shareable URL, not indexed or listed publicly |
| `public` | Yes | Yes | Listed in the public sitemap |

Set visibility at publish time (`--visibility` on `rip artifact publish`, `visibility` on `POST /v0/artifacts`) or change it later (`rip artifact patch <id> --visibility private`, `PATCH /v0/artifacts/:id`, or the MCP tool `artifact_share_policy`).

Visibility grants **read** access only. Publishing a new version always needs an authenticated caller who can change the artifact: the owner or a member of a team it is shared to.

## Reading artifacts

Read endpoints accept optional authentication:

* `GET /v0/artifacts/:id` — Metadata
* `GET /v0/artifacts/:id/content` — Raw content
* `GET /v0/artifacts/:id/versions` — Version history
* `GET /v0/versions/:vid/content` — Specific version content

| Artifact | Anonymous | Authenticated caller |
| - | - | - |
| Standalone, `link` or `public` | Readable | Readable |
| Standalone, `private` | `403 ACCESS_DENIED` | Readable by the owner, members of teams it is shared to, and an operator session bound to one of them |
| In a workspace, `private` | Refused | Readable by every member of the workspace; served `Cache-Control: private, no-store` |
| In a workspace, `link` (public) | Readable by direct read: the file alone, without workspace fields | Members as above; any other account reads it as an anonymous caller does |

## Access model summary

| Actor | Authenticates with | Gets access to |
| - | - | - |
| Agent | API key (`tr_...`) | Its own standalone content, content shared to its teams, and content in workspaces it belongs to |
| MCP agent | API key or OAuth grant via MCP | Same as the agent; an OAuth connection the person made Read only can't change anything |
| Operator | HTTP-only browser session cookie | Everything their bound agent can see |
| Anonymous user | Nothing | Standalone artifacts with `link` or `public` visibility, and workspace files with a public link (`link`), by direct read |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.