# Get a board

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

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

One board, whole: its columns in order with their cards (oldest
first), each card's reactions, comments, net `vote_score` and the
caller's own vote in `my_vote`, the board's action items, and its
timer. Empty `columns`, `action_items`, `reactions` and `comments`
are left out.

Requires the `retro:board:read` 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.

## Responses

### 200 — The board.

Content type: `application/json`

Type: `BoardEnvelope`

- `success` (boolean)
- `data` (Board)
  - `id` (string, example `brd_3f9a1c7e2b8d4a60`)
  - `org_id` (string)
  - `name` (string)
  - `description` (string)
  - `status` (string, one of `active`, `closed`)
  - `team_id` (string): The team the board belongs to, or `""` for the whole organization.
  - `visibility` (Visibility, one of `org`, `team`, `private`)
  - `created_by` (string): The user ID (or, for an organization key, the key's ID) that created the board.
  - `created_at` (string (date-time))
  - `voting_enabled` (boolean)
  - `comments_enabled` (boolean)
  - `sort_by_votes` (boolean): Every column's cards are ordered highest vote first, for everyone.
  - `share_mode` (ShareMode, one of `disabled`, `read_only`, `participate`)
  - `share_token` (string): The credential the board's share link carries.
  - `share_url` (string): The board's share link; left out while sharing is `disabled`.
  - `timer` (Timer)
    - `state` (string, one of `idle`, `running`, `paused`): A running timer whose end has passed stays `running` with `remaining_ms` 0 until it is stopped.
    - `ends_at` (string (date-time)): When a running countdown ends; left out otherwise.
    - `remaining_ms` (integer (int64)): Time left, in milliseconds.
    - `server_time` (string (date-time)): The server's clock when the timer was read.
  - `columns` (array of Column): Only when one board is read; left out when the board has none.
    - `id` (string, example `col_1a2b3c4d5e6f7a80`)
    - `board_id` (string)
    - `name` (string)
    - `emoji` (string)
    - `color` (string)
    - `position` (integer)
    - `sort_order` (integer)
    - `created_at` (string (date-time))
    - `cards` (array of Card): Only when a whole board is read.
  - `action_items` (array of ActionItem): Only when one board is read; left out when the board has none.
    - `id` (string, example `act_5b2e8c1d9f4a7e30`)
    - `board_id` (string)
    - `description` (string)
    - `assignee` (string): A free-text owner name; `""` when none.
    - `assignee_user_id` (string | null): The organization member who owns the item.
    - `status` (string, one of `open`, `done`)
    - `created_at` (string (date-time))
    - `updated_at` (string (date-time)): When the item last changed.
    - `completed_at` (string (date-time) | null): When the item was marked done; `null` while open, and for some items done before this was recorded.
    - `due_at` (string (date-time) | null)

### 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 GET 'https://evohub.io/api/v1/retro/boards/brd_3f9a1c7e2b8d4a60' \
  -H 'Authorization: Bearer <TOKEN>'
```