# Create a board

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

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

Creates an active board with no columns; add them with
`POST /api/v1/retro/boards/{boardID}/columns`. Voting and comments
are on, and the board gets a working share link in `participate`
mode (change it with `PATCH /api/v1/retro/boards/{boardID}/share`).
Whoever creates the board is named on it, so a `private` board stays
visible to them.

- `name` is required, at most 200 characters.
- `team_id` must be a team the caller is in, or `""` (the default) for
  the whole organization; otherwise **403** `NOT_IN_TEAM`.
- `visibility` defaults to `team` when a team is given and `org`
  otherwise. A `team` board needs a `team_id`.

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

## Request body (required)

Content type: `application/json`

Type: `CreateBoardRequest`

- `name` (string, required, max length 200)
- `description` (string)
- `team_id` (string): A team the caller is in, or `""` (the default) for the whole organization.
- `visibility` (Visibility, one of `org`, `team`, `private`)

## Responses

### 201 — The board was created.

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)

### 400 — The body is not JSON (`INVALID_BODY`), `name` is missing or blank (`MISSING_NAME`), `name` is over 200 characters (`VALIDATION_FAILED`, in the `ValidationFailed` shape), `visibility` is not `org`, `team` or `private` (`INVALID_VISIBILITY`), or a `team` board has no `team_id` (`TEAM_REQUIRED`).

Content type: `application/json`

Type: `Error | ValidationFailed`

- One of:
  - 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)
  - ValidationFailed
    - `success` (boolean, value `false`)
    - `error` (object, required)
      - `code` (string, required, value `VALIDATION_FAILED`)
      - `message` (string, required)
      - `details` (array of object, required)
        - `field` (string)
        - `message` (string)
      - `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 `retro:board:write` (`FORBIDDEN`), or `team_id` names a team the caller is not in (`NOT_IN_TEAM`).

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 POST 'https://evohub.io/api/v1/retro/boards' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <TOKEN>' \
  -d '{
  "name": "Sprint 42 retro",
  "team_id": "team_6a1f3e9c2d7b4058",
  "description": "What went well and what to change after sprint 42"
}'
```