# guests

 6 routes, from the API’s own OpenAPI document.

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

6 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}/​guests`](#get-v1-apps-id-guests) | An app's guests, and whether the workspace lets anyone invite one |
| [[POST]] | [`/​v1/​apps/​{id}/​guests`](#post-v1-apps-id-guests) | Invite people outside the workspace to open this one app |
| [[DELETE]] | [`/​v1/​apps/​{id}/​guests/​{guestId}`](#delete-v1-apps-id-guests-guestid) | End a guest’s access now; for a guest whose access is over, forget them |
| [[POST]] | [`/​v1/​apps/​{id}/​guests/​{guestId}/​resend`](#post-v1-apps-id-guests-guestid-resend) | A fresh link for a guest whose access still runs (the old link stops working) |
| [[GET]] | [`/​v1/​workspaces/​{ws}/​guests`](#get-v1-workspaces-ws-guests) | Every guest of the workspace and whether guests are on (admins) |
| [[PUT]] | [`/​v1/​workspaces/​{ws}/​guests/​policy`](#put-v1-workspaces-ws-guests-policy) | Turn guests on or off for the workspace (admins). Off ends every open guest. |

## Reference

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

An app's guests, and whether the workspace lets anyone invite one.

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** `can_share` (owner, admins); not for tokens

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

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `enabled` | boolean | yes |  |
| `offReason` | "profile" · "policy" · null or null | yes |  |
| `canTurnOn` | boolean | yes |  |
| `canInvite` | boolean | yes |  |
| `open` | integer | yes | at least 0 |
| `limit` | integer | yes | at least 1 |
| `items` | object[] | yes |  |
| `items[].id` | string | yes | at least 1 characters |
| `items[].appId` | string | yes | at least 1 characters |
| `items[].appName` | string | yes |  |
| `items[].email` | string | yes | at least 3 characters |
| `items[].role` | "viewer" · "runner" | yes |  |
| `items[].status` | "invited" · "active" · "expired" · "revoked" | yes |  |
| `items[].invitedBy` | string | yes |  |
| `items[].createdAt` | string (date-time) | yes |  |
| `items[].expiresAt` | string (date-time) | yes |  |
| `items[].lastOpenedAt` | string (date-time) or null | yes |  |
| `items[].opens` | integer | yes | at least 0 |
| `items[].revokedAt` | string (date-time) or null | yes |  |

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

### [[POST]] `/v1/apps/{id}/guests`

Invite people outside the workspace to open this one app.

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** `can_share`

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

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

| Field | Type | Required | Notes |
|---|---|---|---|
| `emails` | string[] | yes | up to 10 items |
| `role` | "viewer" · "runner" |  | default "viewer" |
| `days` | integer |  | 1 to 30. default 7 |
| `deliver` | "email" · "link" |  | default "email" |
| `locale` | "en" · "ru" · "kk" |  |  |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `items` | object[] | yes |  |
| `items[].id` | string | yes | at least 1 characters |
| `items[].appId` | string | yes | at least 1 characters |
| `items[].appName` | string | yes |  |
| `items[].email` | string | yes | at least 3 characters |
| `items[].role` | "viewer" · "runner" | yes |  |
| `items[].status` | "invited" · "active" · "expired" · "revoked" | yes |  |
| `items[].invitedBy` | string | yes |  |
| `items[].createdAt` | string (date-time) | yes |  |
| `items[].expiresAt` | string (date-time) | yes |  |
| `items[].lastOpenedAt` | string (date-time) or null | yes |  |
| `items[].opens` | integer | yes | at least 0 |
| `items[].revokedAt` | string (date-time) or null | yes |  |
| `links` | object[] | yes |  |
| `links[].guestId` | string | yes | at least 1 characters |
| `links[].email` | string | yes |  |
| `links[].link` | string (uri) | yes |  |
| `delivery` | "email" · "dev-log" · null or null | yes |  |

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

### [[DELETE]] `/v1/apps/{id}/guests/{guestId}`

End a guest’s access now; for a guest whose access is over, forget them.

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** `can_share`

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

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `removed` | boolean | yes |  |
| `guest` | object or null | yes |  |
| `guest.id` | string | yes | at least 1 characters |
| `guest.appId` | string | yes | at least 1 characters |
| `guest.appName` | string | yes |  |
| `guest.email` | string | yes | at least 3 characters |
| `guest.role` | "viewer" · "runner" | yes |  |
| `guest.status` | "invited" · "active" · "expired" · "revoked" | yes |  |
| `guest.invitedBy` | string | yes |  |
| `guest.createdAt` | string (date-time) | yes |  |
| `guest.expiresAt` | string (date-time) | yes |  |
| `guest.lastOpenedAt` | string (date-time) or null | yes |  |
| `guest.opens` | integer | yes | at least 0 |
| `guest.revokedAt` | string (date-time) or null | yes |  |

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

### [[POST]] `/v1/apps/{id}/guests/{guestId}/resend`

A fresh link for a guest whose access still runs (the old link stops working).

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** `can_share`

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

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

| Field | Type | Required | Notes |
|---|---|---|---|
| `deliver` | "email" · "link" |  | default "email" |
| `locale` | "en" · "ru" · "kk" |  |  |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `items` | object[] | yes |  |
| `items[].id` | string | yes | at least 1 characters |
| `items[].appId` | string | yes | at least 1 characters |
| `items[].appName` | string | yes |  |
| `items[].email` | string | yes | at least 3 characters |
| `items[].role` | "viewer" · "runner" | yes |  |
| `items[].status` | "invited" · "active" · "expired" · "revoked" | yes |  |
| `items[].invitedBy` | string | yes |  |
| `items[].createdAt` | string (date-time) | yes |  |
| `items[].expiresAt` | string (date-time) | yes |  |
| `items[].lastOpenedAt` | string (date-time) or null | yes |  |
| `items[].opens` | integer | yes | at least 0 |
| `items[].revokedAt` | string (date-time) or null | yes |  |
| `links` | object[] | yes |  |
| `links[].guestId` | string | yes | at least 1 characters |
| `links[].email` | string | yes |  |
| `links[].link` | string (uri) | yes |  |
| `delivery` | "email" · "dev-log" · null or null | yes |  |

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}/guests`

Every guest of the workspace and whether guests are on (admins).

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** admin

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

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `enabled` | boolean | yes |  |
| `offReason` | "profile" · "policy" · null or null | yes |  |
| `canTurnOn` | boolean | yes |  |
| `canInvite` | boolean | yes |  |
| `open` | integer | yes | at least 0 |
| `limit` | integer | yes | at least 1 |
| `items` | object[] | yes |  |
| `items[].id` | string | yes | at least 1 characters |
| `items[].appId` | string | yes | at least 1 characters |
| `items[].appName` | string | yes |  |
| `items[].email` | string | yes | at least 3 characters |
| `items[].role` | "viewer" · "runner" | yes |  |
| `items[].status` | "invited" · "active" · "expired" · "revoked" | yes |  |
| `items[].invitedBy` | string | yes |  |
| `items[].createdAt` | string (date-time) | yes |  |
| `items[].expiresAt` | string (date-time) | yes |  |
| `items[].lastOpenedAt` | string (date-time) or null | yes |  |
| `items[].opens` | integer | yes | at least 0 |
| `items[].revokedAt` | string (date-time) or null | yes |  |

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

### [[PUT]] `/v1/workspaces/{ws}/guests/policy`

Turn guests on or off for the workspace (admins). Off ends every open guest..

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** admin

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

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

| Field | Type | Required | Notes |
|---|---|---|---|
| `allowed` | boolean | yes |  |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `enabled` | boolean | yes |  |
| `offReason` | "profile" · "policy" · null or null | yes |  |
| `canTurnOn` | boolean | yes |  |
| `canInvite` | boolean | yes |  |
| `open` | integer | yes | at least 0 |
| `limit` | integer | yes | at least 1 |
| `items` | object[] | yes |  |
| `items[].id` | string | yes | at least 1 characters |
| `items[].appId` | string | yes | at least 1 characters |
| `items[].appName` | string | yes |  |
| `items[].email` | string | yes | at least 3 characters |
| `items[].role` | "viewer" · "runner" | yes |  |
| `items[].status` | "invited" · "active" · "expired" · "revoked" | yes |  |
| `items[].invitedBy` | string | yes |  |
| `items[].createdAt` | string (date-time) | yes |  |
| `items[].expiresAt` | string (date-time) | yes |  |
| `items[].lastOpenedAt` | string (date-time) or null | yes |  |
| `items[].opens` | integer | yes | at least 0 |
| `items[].revokedAt` | string (date-time) or null | yes |  |

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