# List boards

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

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

Every board the caller can see, newest first, without their columns,
cards or action items (read one board for those).

`data` is `[]` when there are no boards.

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_…`).

## Query parameters

- `team_id` (string, example `none`): Narrow to one team's boards plus the organization-wide ones, or `none` for only the organization-wide ones. It never widens what the caller can see.

## Responses

### 200 — The boards.

Content type: `application/json`

Type: `object`

- `success` (boolean)
- `data` (array of 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)

### 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' \
  -H 'Authorization: Bearer <TOKEN>'
```