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.
3 routes. Every path starts at https://cloud-api.qaldy.com. Sign-in, tokens, errors and limits are on the overview.
Routes#
| Method | Path | What it does |
|---|---|---|
| GET | /v1/apps/{id}/share | Who can open, run and edit an app |
| PATCH | /v1/apps/{id}/share | Change sharing (owner only; public links need admin + policy + a form) |
| 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
readscope. - Who:
can_view(canSharereflectscan_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).
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
writescope. - Who:
can_share;linkneeds 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).
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
readscope. - 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).