# Sharing

Who can open an app, and how: people, teams, the workspace and (where policy allows) a link. 3 routes, from the API’s own OpenAPI document.

URL: https://docs.qaldy.com/reference/api/share/

3 routes. Every path starts at `https://cloud-api.qaldy.com`. Sign-in, tokens, errors and limits are on the [overview](https://docs.qaldy.com/reference/api/).

## Routes

| Method | Path | What it does |
|---|---|---|
| [[GET]] | [`/​v1/​apps/​{id}/​share`](#get-v1-apps-id-share) | Who can open, run and edit an app |
| [[PATCH]] | [`/​v1/​apps/​{id}/​share`](#patch-v1-apps-id-share) | Change sharing (owner only; public links need admin + policy + a form) |
| [[GET]] | [`/​v1/​workspaces/​{ws}/​principals`](#get-v1-workspaces-ws-principals) | People and teams of this workspace, for the share picker |

## Reference

### [[GET]] `/v1/apps/{id}/share`

Who can open, run and edit an app.

- **Authentication:** the console’s session cookie.
- **Token:** a personal access token or an MCP sign-in with the `read` scope.
- **Who:** `can_view` (`canShare` reflects `can_share`)

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `id` | path | string | yes | 1 to 128 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `appId` | string | yes | at least 1 characters |
| `owner` | object | yes |  |
| `owner.kind` | "user" | yes |  |
| `owner.id` | string | yes | at least 1 characters |
| `owner.name` | string | yes | at least 1 characters |
| `owner.email` | string | yes | at least 3 characters |
| `owner.initials` | string | yes | 1 to 3 characters |
| `owner.color` | "sky" · "pool" · "bubblegum" · "leaf" · "lilac" · "sun" · "tangerine" · "tomato" | yes |  |
| `grants` | object[] | yes |  |
| `grants[].principal` | object | yes |  |
| `grants[].role` | "viewer" · "runner" · "editor" | yes |  |
| `generalAccess` | "restricted" · "team" · "workspace" · "link" | yes |  |
| `generalRole` | "viewer" · "runner" · "editor" | yes |  |
| `teamId` | string or null | yes |  |
| `canShare` | boolean | yes |  |
| `linkAllowed` | boolean | yes |  |
| `linkDisabledReason` | "policy" · "app-type" · "not-admin" · null or null | yes |  |
| `guests` | integer |  | at least 0 |
| `publicProbe` | object |  |  |
| `publicProbe.state` | "ready" · "needs_check" · "stale" · "running" · "blocked" · "unavailable" | yes |  |
| `publicProbe.probeId` | string or null | yes |  |
| `publicProbe.reason` | string or null | yes | up to 400 characters |

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[PATCH]] `/v1/apps/{id}/share`

Change sharing (owner only; public links need admin + policy + a form).

- **Authentication:** the console’s session cookie.
- **Token:** a personal access token or an MCP sign-in with the `write` scope.
- **Who:** `can_share`; `link` needs admin + policy + public-safe type, a current unblocked exposure check and a typed confirm (`publicConfirm`)

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `id` | path | string | yes | 1 to 128 characters |

**Request body** (`application/json`)

| Field | Type | Required | Notes |
|---|---|---|---|
| `generalAccess` | "restricted" · "team" · "workspace" · "link" |  |  |
| `generalRole` | "viewer" · "runner" · "editor" |  |  |
| `teamId` | string or null |  |  |
| `upsert` | object[] |  |  |
| `upsert[].kind` | "user" · "team" | yes |  |
| `upsert[].id` | string | yes | at least 1 characters |
| `upsert[].role` | "viewer" · "runner" · "editor" | yes |  |
| `remove` | object[] |  |  |
| `remove[].kind` | "user" · "team" | yes |  |
| `remove[].id` | string | yes | at least 1 characters |
| `publicConfirm` | object |  |  |
| `publicConfirm.probeId` | string | yes | 1 to 128 characters |
| `publicConfirm.typed` | string | yes | 1 to 120 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `appId` | string | yes | at least 1 characters |
| `owner` | object | yes |  |
| `owner.kind` | "user" | yes |  |
| `owner.id` | string | yes | at least 1 characters |
| `owner.name` | string | yes | at least 1 characters |
| `owner.email` | string | yes | at least 3 characters |
| `owner.initials` | string | yes | 1 to 3 characters |
| `owner.color` | "sky" · "pool" · "bubblegum" · "leaf" · "lilac" · "sun" · "tangerine" · "tomato" | yes |  |
| `grants` | object[] | yes |  |
| `grants[].principal` | object | yes |  |
| `grants[].role` | "viewer" · "runner" · "editor" | yes |  |
| `generalAccess` | "restricted" · "team" · "workspace" · "link" | yes |  |
| `generalRole` | "viewer" · "runner" · "editor" | yes |  |
| `teamId` | string or null | yes |  |
| `canShare` | boolean | yes |  |
| `linkAllowed` | boolean | yes |  |
| `linkDisabledReason` | "policy" · "app-type" · "not-admin" · null or null | yes |  |
| `guests` | integer |  | at least 0 |
| `publicProbe` | object |  |  |
| `publicProbe.state` | "ready" · "needs_check" · "stale" · "running" · "blocked" · "unavailable" | yes |  |
| `publicProbe.probeId` | string or null | yes |  |
| `publicProbe.reason` | string or null | yes | up to 400 characters |

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[GET]] `/v1/workspaces/{ws}/principals`

People and teams of this workspace, for the share picker.

- **Authentication:** the console’s session cookie.
- **Token:** a personal access token or an MCP sign-in with the `read` scope.
- **Who:** member

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |
| `q` | query | string |  | up to 100 characters |

**Response 200**

A object[].

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).