# Workspaces and invites

Create a workspace, switch between yours, and accept an invite. 8 routes, from the API’s own OpenAPI document.

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

8 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 |
|---|---|---|
| [[POST]] | [`/​v1/​invites/​{token}/​accept`](#post-v1-invites-token-accept) | Join a workspace from an invite link (the invited, verified email only) |
| [[GET]] | [`/​v1/​workspaces`](#get-v1-workspaces) | Who is signed in and every workspace they are in |
| [[POST]] | [`/​v1/​workspaces`](#post-v1-workspaces) | Create a workspace with a starter world (a working sample app, gates, a road) |
| [[GET]] | [`/​v1/​workspaces/​{ws}/​invites`](#get-v1-workspaces-ws-invites) | Invites of a workspace, newest first (admins) |
| [[POST]] | [`/​v1/​workspaces/​{ws}/​invites`](#post-v1-workspaces-ws-invites) | Invite people by email with a role (admins); each gets a join link |
| [[DELETE]] | [`/​v1/​workspaces/​{ws}/​invites/​{inviteId}`](#delete-v1-workspaces-ws-invites-inviteid) | Revoke an open invite (admins) |
| [[POST]] | [`/​v1/​workspaces/​{ws}/​invites/​{inviteId}/​resend`](#post-v1-workspaces-ws-invites-inviteid-resend) | Send an open invite again with a fresh link; the old link stops working (admins) |
| [[POST]] | [`/​v1/​workspaces/​{ws}/​switch`](#post-v1-workspaces-ws-switch) | Open another of your workspaces in this session |

## Reference

### [[POST]] `/v1/invites/{token}/accept`

Join a workspace from an invite link (the invited, verified email only).

- **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:** signed in

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `token` | path | string | yes |  |

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

An empty object: `{}`.

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `session` | object | yes |  |
| `session.user` | object | yes |  |
| `session.workspaceId` | string | yes | at least 1 characters |
| `session.workspaceRole` | "owner" · "admin" · "builder" · "member" · "viewer" | yes |  |
| `session.devLogin` | boolean | 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`

Who is signed in and every workspace they are in.

- **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).

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `user` | object | yes |  |
| `user.kind` | "user" | yes |  |
| `user.id` | string | yes | at least 1 characters |
| `user.name` | string | yes | at least 1 characters |
| `user.email` | string | yes | at least 3 characters |
| `user.initials` | string | yes | 1 to 3 characters |
| `user.color` | "sky" · "pool" · "bubblegum" · "leaf" · "lilac" · "sun" · "tangerine" · "tomato" | yes |  |
| `items` | object[] | yes |  |
| `items[].id` | string | yes | at least 1 characters |
| `items[].name` | string | yes | at least 1 characters |
| `items[].slug` | string | yes | at least 1 characters |
| `items[].profile` | "global" · "eu" · "kz-standard" · "kz-strict" | yes |  |
| `items[].role` | "owner" · "admin" · "builder" · "member" · "viewer" | yes |  |
| `items[].memberCount` | integer | yes | at least 0 |
| `currentId` | string or null | yes | at least 1 characters |

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

### [[POST]] `/v1/workspaces`

Create a workspace with a starter world (a working sample app, gates, a road).

- **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).

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

| Field | Type | Required | Notes |
|---|---|---|---|
| `name` | string | yes | 2 to 60 characters |
| `profile` | "global" · "eu" · "kz-standard" · "kz-strict" | yes |  |
| `teamSize` | "solo" · "small" · "medium" · "large" | yes |  |
| `intents` | string[] | yes | up to 3 items |
| `locale` | "en" · "ru" · "kk" |  |  |
| `timezone` | string |  | up to 64 characters |
| `currency` | "EUR" · "USD" · "KZT" |  |  |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `workspace` | object | yes |  |
| `workspace.id` | string | yes | at least 1 characters |
| `workspace.slug` | string | yes | at least 1 characters |
| `workspace.name` | string | yes | at least 1 characters |
| `workspace.profile` | "global" · "eu" · "kz-standard" · "kz-strict" | yes |  |
| `workspace.cell` | "global" · "eu" · "kz" | yes |  |
| `workspace.locale` | "en" · "ru" · "kk" | yes |  |
| `workspace.timezone` | string | yes | at least 1 characters |
| `workspace.hourlyCostMinor` | integer | yes | at least 0 |
| `workspace.currency` | "EUR" · "USD" · "KZT" | yes |  |
| `workspace.memberCount` | integer | yes | at least 0 |
| `session` | object | yes |  |
| `session.user` | object | yes |  |
| `session.workspaceId` | string | yes | at least 1 characters |
| `session.workspaceRole` | "owner" · "admin" · "builder" · "member" · "viewer" | yes |  |
| `session.devLogin` | boolean | yes |  |
| `starter` | object | yes |  |
| `starter.sampleAppId` | string or null | yes | at least 1 characters |
| `starter.appIds` | string[] | yes |  |
| `starter.gateIds` | string[] | yes |  |
| `starter.roadIds` | string[] | 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}/invites`

Invites of a workspace, newest first (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 |
|---|---|---|---|
| `items` | object[] | yes |  |
| `items[].id` | string | yes | at least 1 characters |
| `items[].email` | string | yes | at least 3 characters |
| `items[].role` | "admin" · "builder" · "member" · "viewer" | yes |  |
| `items[].status` | "pending" · "accepted" · "revoked" · "expired" | yes |  |
| `items[].invitedBy` | string | yes | at least 1 characters |
| `items[].createdAt` | string (date-time) | yes |  |
| `items[].expiresAt` | string (date-time) | yes |  |
| `items[].accessEndsAt` | string (date-time) or null |  | default null |

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

### [[POST]] `/v1/workspaces/{ws}/invites`

Invite people by email with a role (admins); each gets a join link.

- **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 |
|---|---|---|---|
| `emails` | string[] | yes | up to 20 items |
| `role` | "admin" · "builder" · "member" · "viewer" | yes |  |
| `expiresInDays` | integer |  | 1 to 30 |
| `accessEndsAt` | string (date-time) |  |  |
| `deliver` | "email" · "link" |  |  |
| `locale` | "en" · "ru" · "kk" |  |  |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `items` | object[] | yes |  |
| `items[].id` | string | yes | at least 1 characters |
| `items[].email` | string | yes | at least 3 characters |
| `items[].role` | "admin" · "builder" · "member" · "viewer" | yes |  |
| `items[].status` | "pending" · "accepted" · "revoked" · "expired" | yes |  |
| `items[].invitedBy` | string | yes | at least 1 characters |
| `items[].createdAt` | string (date-time) | yes |  |
| `items[].expiresAt` | string (date-time) | yes |  |
| `items[].accessEndsAt` | string (date-time) or null |  | default null |
| `delivery` | "email" · "dev-log" · null or null | yes |  |
| `links` | object[] |  | default |
| `links[].inviteId` | string | yes | at least 1 characters |
| `links[].email` | string | yes | at least 3 characters |
| `links[].link` | string | yes | at least 10 characters |

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

### [[DELETE]] `/v1/workspaces/{ws}/invites/{inviteId}`

Revoke an open invite (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 |
| `inviteId` | path | string | yes |  |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `ok` | true | yes |  |

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

### [[POST]] `/v1/workspaces/{ws}/invites/{inviteId}/resend`

Send an open invite again with a fresh link; the old link stops working (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 |
| `inviteId` | path | string | yes |  |

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

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

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `items` | object[] | yes |  |
| `items[].id` | string | yes | at least 1 characters |
| `items[].email` | string | yes | at least 3 characters |
| `items[].role` | "admin" · "builder" · "member" · "viewer" | yes |  |
| `items[].status` | "pending" · "accepted" · "revoked" · "expired" | yes |  |
| `items[].invitedBy` | string | yes | at least 1 characters |
| `items[].createdAt` | string (date-time) | yes |  |
| `items[].expiresAt` | string (date-time) | yes |  |
| `items[].accessEndsAt` | string (date-time) or null |  | default null |
| `delivery` | "email" · "dev-log" · null or null | yes |  |
| `links` | object[] |  | default |
| `links[].inviteId` | string | yes | at least 1 characters |
| `links[].email` | string | yes | at least 3 characters |
| `links[].link` | string | yes | at least 10 characters |

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

### [[POST]] `/v1/workspaces/{ws}/switch`

Open another of your workspaces in this session.

- **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).

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

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

An empty object: `{}`.

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `user` | object | yes |  |
| `user.kind` | "user" | yes |  |
| `user.id` | string | yes | at least 1 characters |
| `user.name` | string | yes | at least 1 characters |
| `user.email` | string | yes | at least 3 characters |
| `user.initials` | string | yes | 1 to 3 characters |
| `user.color` | "sky" · "pool" · "bubblegum" · "leaf" · "lilac" · "sun" · "tangerine" · "tomato" | yes |  |
| `workspaceId` | string | yes | at least 1 characters |
| `workspaceRole` | "owner" · "admin" · "builder" · "member" · "viewer" | yes |  |
| `devLogin` | boolean | yes |  |

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