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

# Sharing runs

> Share Revilico runs with people in your organization through the REST API or MCP server, list and revoke shares, and list runs others shared with you.

Sharing a run gives someone in your organization read access to it, as **Pipeline sharing** does in the web app's Command Center. The run then shows in their Command Center and in their API and MCP calls.

## What a share gives

People a run is shared with can:

* see the run, its status and its credits
* read its results, list and read its files, and download its outputs
* share it on with others in the organization

They can't cancel it or read its inputs. The inputs, meaning the parameters and input files a run was started with, stay with the person who started it. `GET /v1/runs/{runId}/inputs` answers `403` to anyone else.

## Who can share, and with whom

* **Who can share:** the run's owner, or anyone the run is shared with. People who only see a run through a project they are in can't share it.
* **Who can receive:** active members of the run owner's organization. You can't share a run with its owner or with yourself.
* Give each person as an email address or a `user_…` id. Up to 20 people per request.
* An email or id that isn't an active member of the organization gets `404 NOT_FOUND`, whether or not the person exists elsewhere.

Sharing with someone who already has the run is not an error. The response counts them in `alreadyShared`.

> [!NOTE]
>
> Nobody is notified when you share a run. Tell people yourself. The one exception: when someone the run was shared with shares it on, the run's owner gets an email.

## Find people to share with

`GET /v1/org/members` lists the active members of your organization other than you, sorted by email. Filter with `q`, which matches names and emails.

```bash theme={null}
curl "https://public-api.revilico.bio/v1/org/members?q=priya" \
  -H "Authorization: Bearer $REVILICO_API_KEY"
```

```json theme={null}
{
  "data": [
    { "id": "user_5b1e…", "name": "Priya Raman", "email": "priya@example.com" }
  ],
  "nextCursor": null
}
```

It needs the `runs:write` scope, the scope that shares, so a read-only key can't list your organization's members.

## Share a run

```bash theme={null}
curl https://public-api.revilico.bio/v1/runs/run_3f2b…/shares \
  -H "Authorization: Bearer $REVILICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "users": ["priya@example.com", "user_9a0c…"] }'
```

The response lists every person you named, now with access:

```json theme={null}
{
  "runId": "run_3f2b…",
  "shared": [
    {
      "id": "share_71d4…",
      "user": { "id": "user_5b1e…", "name": "Priya Raman", "email": "priya@example.com" },
      "sharedBy": { "name": "Alex Kim", "email": "alex@example.com" },
      "via": "share",
      "sharedAt": "2026-10-27T10:12:44.000Z"
    }
  ],
  "created": 1,
  "alreadyShared": 1,
  "notice": "Shared people can see the run's status, results, outputs and files, and share it on. …"
}
```

## See who a run is shared with

`GET /v1/runs/{runId}/shares` lists the shares. The owner sees every share, including the ones made by people who shared the run on. Anyone else sees only the shares they made or received.

`via` says where a share came from:

| `via` | Meaning |
| - | - |
| `share` | Shared directly, in the web app or through the API |
| `compound_review` | Given by a [compound review](https://docs.revilico.bio/docs/revcompound-review.md) the person is in. It goes when they leave the review. |

## Stop sharing

```bash theme={null}
curl -X DELETE https://public-api.revilico.bio/v1/runs/run_3f2b…/shares/share_71d4… \
  -H "Authorization: Bearer $REVILICO_API_KEY"
```

The run's owner, the person who made the share, or the person it was shared with can remove it.

Removing a share also removes everyone that person shared the run with, and everyone they shared it with, and so on. `revoked` lists everyone who lost access:

```json theme={null}
{
  "runId": "run_3f2b…",
  "revoked": [
    { "id": "user_5b1e…", "name": "Priya Raman", "email": "priya@example.com" },
    { "id": "user_2c88…", "name": "Sam Ortiz", "email": "sam@example.com" }
  ]
}
```

A share with `via: compound_review` answers `409 CONFLICT`. Remove the person from the compound review instead.

## Runs shared with you

`GET /v1/runs` lists only runs you started, unless you ask for more with `ownership`:

| `ownership` | Lists |
| - | - |
| `owned` (default) | Runs you started |
| `shared` | Runs others shared with you |
| `project` | Other members' runs in projects you are in |
| `all` | Every run you can see |

```bash theme={null}
curl "https://public-api.revilico.bio/v1/runs?ownership=shared" \
  -H "Authorization: Bearer $REVILICO_API_KEY"
```

Every run says who started it and how you can see it:

```json theme={null}
{
  "id": "run_3f2b…",
  "engine": "revredox",
  "access": "shared",
  "owner": { "name": "Alex Kim", "email": "alex@example.com" },
  "status": "succeeded",
  …
}
```

`access` is `owner`, `shared` or `project`. Only the owner can cancel a run or read its inputs.

## Scopes

| Action | Scope |
| - | - |
| List runs, see a run's shares | `runs:read` |
| Share, stop sharing, list organization members | `runs:write` |

## MCP tools

| Tool | Does |
| - | - |
| `list_org_members` | Lists the people you can share with |
| `share_run` | Shares a run with people, by email or user id |
| `list_run_shares` | Lists who a run is shared with, with share ids |
| `unshare_run` | Removes a share, and everyone that person shared it on to |
| `list_runs` | Takes `ownership`, as above |

For example: "Share my last RevScreen run with Priya." The app finds the run, finds Priya with `list_org_members`, and confirms with you before it calls `share_run`. See the [tools reference](https://docs.revilico.bio/developers/mcp/tools.md#sharing) for each tool's arguments.


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