# Set the share mode

`PATCH https://evohub.io/api/v1/retro/boards/{boardID}/share`

Part of the [Retro API](https://docs.evohub.io/retro.md) reference · operationId `updateRetroShareMode`.

Sets what the board's share link lets a guest do:

| `mode` | A guest with the link |
| --- | --- |
| `disabled` | Cannot open the board. |
| `read_only` | Can view the board. |
| `participate` | Can view it and add cards, comments, reactions and votes, and edit or delete their own. |

The share mode never limits members of the organization. To revoke
links already handed out, rotate the token.

Requires the `retro:board:write` scope.

## Authorization

Any one of:

- `bearerKey`
- `headerKey`

Where:

- `bearerKey`: HTTP Bearer — An EvoHub API key (`evohub_…`) as a bearer token.
- `headerKey`: API key in the header `X-API-Key` — An EvoHub API key (`evohub_…`).

## Path parameters

- `boardID` (string, required, example `brd_3f9a1c7e2b8d4a60`): The board's ID.

## Request body (required)

Content type: `application/json`

Type: `object`

- `mode` (ShareMode, required, one of `disabled`, `read_only`, `participate`)

## Responses

### 200 — The share mode was set.

Content type: `application/json`

Type: `object`

- `success` (boolean)
- `data` (object)
  - `share_mode` (ShareMode, one of `disabled`, `read_only`, `participate`)

### 400 — The body is not JSON (`INVALID_BODY`), or `mode` is not `disabled`, `read_only` or `participate` (`INVALID_MODE`).

Content type: `application/json`

Type: `Error`

- `success` (boolean, value `false`): Sent by Retro itself; refusals before the request reaches Retro (401, 429) carry only `error`.
- `error` (object, required)
  - `code` (string, required, example `NOT_FOUND`)
  - `message` (string, required, example `board not found`)
  - `request_id` (string)

### 401 — No API key was sent, or it is unknown, revoked or expired (`UNAUTHORIZED`).

Content type: `application/json`

Type: `Error`

- `success` (boolean, value `false`): Sent by Retro itself; refusals before the request reaches Retro (401, 429) carry only `error`.
- `error` (object, required)
  - `code` (string, required, example `NOT_FOUND`)
  - `message` (string, required, example `board not found`)
  - `request_id` (string)

### 403 — The key lacks the scope this endpoint needs (`FORBIDDEN`).

Content type: `application/json`

Type: `Error`

- `success` (boolean, value `false`): Sent by Retro itself; refusals before the request reaches Retro (401, 429) carry only `error`.
- `error` (object, required)
  - `code` (string, required, example `NOT_FOUND`)
  - `message` (string, required, example `board not found`)
  - `request_id` (string)

### 404 — The board does not exist, or the caller cannot see it (`NOT_FOUND`).

Content type: `application/json`

Type: `Error`

- `success` (boolean, value `false`): Sent by Retro itself; refusals before the request reaches Retro (401, 429) carry only `error`.
- `error` (object, required)
  - `code` (string, required, example `NOT_FOUND`)
  - `message` (string, required, example `board not found`)
  - `request_id` (string)

### 429 — Too many requests (`RATE_LIMITED`). Wait for `Retry-After` seconds.

Headers:

- `Retry-After` (integer): Seconds to wait before retrying.

Content type: `application/json`

Type: `Error`

- `success` (boolean, value `false`): Sent by Retro itself; refusals before the request reaches Retro (401, 429) carry only `error`.
- `error` (object, required)
  - `code` (string, required, example `NOT_FOUND`)
  - `message` (string, required, example `board not found`)
  - `request_id` (string)

### 500 — Something went wrong on EvoHub's side (`INTERNAL_ERROR`). Retry later.

Content type: `application/json`

Type: `Error`

- `success` (boolean, value `false`): Sent by Retro itself; refusals before the request reaches Retro (401, 429) carry only `error`.
- `error` (object, required)
  - `code` (string, required, example `NOT_FOUND`)
  - `message` (string, required, example `board not found`)
  - `request_id` (string)

## Example request

```bash
curl -X PATCH 'https://evohub.io/api/v1/retro/boards/brd_3f9a1c7e2b8d4a60/share' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <TOKEN>' \
  -d '{
  "mode": "read_only"
}'
```