# Board API

Version 1.0 · OpenAPI 3.1.0

Manage EvoHub Board from scripts and CI: create boards from a template,
add lists and cards, move work across the board, assign people, set due
dates, labels and checklists, comment, link cards to things in other
EvoHub products, and drive the review gate that signs work off before it
counts as done.

**Authentication.** Every endpoint takes an EvoHub API key, sent as
`Authorization: Bearer evohub_…` or as `X-API-Key: evohub_…`. Each
operation names the scope the key needs in its description and in
`x-evohub-permission`. A missing or invalid key gets **401**; a valid key
without the scope gets **403**, never 401. A key holds exactly its scopes
and never counts as an organization administrator. See the
[API overview](/api-overview), [API keys and scopes](/api-keys-and-scopes)
and [Errors](/errors).

**Who a key acts as.** A personal key acts as the person who created it,
with that person's teams. An organization key acts as itself: comments,
approvals and the activity trail name the key, and it sees the world as
the team it was configured with, if any.

**Visibility.** A board is `private` (only the people named on it), `team`
(everyone in the board's own team, `team_id`) or `org` (everyone in the
organization). Anyone named on a board sees it whatever its visibility,
and so does every member of a team the board was given to. Whoever creates
a board is named on it. Visibility decides only who sees a board; what a
caller may do on it is the scope. A board, list, card, label, checklist
item, comment or link the caller cannot see answers **404** `NOT_FOUND`,
exactly like one that does not exist.

**Responses.** A successful answer carries its result in `data`. The
analytics endpoint also sends `"success": true`. Errors carry an `error`
object with a machine-readable `code`. Timestamps are RFC 3339 in UTC.
Request bodies are JSON and may not contain fields the endpoint does not
know (`INVALID_BODY`).

**Placement.** Lists, cards and checklist items are placed by naming the
neighbours they land between (`after`, `before`), or an end of the list
(`to`: `top` or `bottom`), never by index. If the named neighbours are no
longer next to each other the request is refused with **409**
`STALE_PLACEMENT`: read the board again and retry.

**Review gate.** A board can mark one list as its review list and one as
its done list. A card moved into the review list waits there until someone
approves or rejects it; nobody assigned to the card may approve it. On a
board with a review list, only an approved card can enter the done list.

## Servers

- `https://evohub.io`

## Authentication

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

## Boards

Create, read, change and archive boards, and the templates a board starts from.

- [GET /api/v1/board/templates](https://docs.evohub.io/board/list-board-templates.md): List board templates
- [GET /api/v1/board/boards](https://docs.evohub.io/board/list-boards.md): List boards
- [POST /api/v1/board/boards](https://docs.evohub.io/board/create-board.md): Create a board
- [GET /api/v1/board/boards/{boardID}](https://docs.evohub.io/board/get-board.md): Get a board
- [DELETE /api/v1/board/boards/{boardID}](https://docs.evohub.io/board/archive-board.md): Archive a board
- [PATCH /api/v1/board/boards/{boardID}](https://docs.evohub.io/board/update-board.md): Update a board

## Sharing

The people and teams named on a board, who see it whatever its visibility.

- [GET /api/v1/board/boards/{boardID}/members](https://docs.evohub.io/board/list-board-members.md): List who a board is shared with
- [POST /api/v1/board/boards/{boardID}/members](https://docs.evohub.io/board/add-board-member.md): Name a person on a board
- [DELETE /api/v1/board/boards/{boardID}/members/{userID}](https://docs.evohub.io/board/remove-board-member.md): Take a person off a board
- [PATCH /api/v1/board/boards/{boardID}/members/{userID}](https://docs.evohub.io/board/update-board-member.md): Update a board member (no effect)
- [POST /api/v1/board/boards/{boardID}/teams](https://docs.evohub.io/board/share-board-with-team.md): Give a board to a team
- [DELETE /api/v1/board/boards/{boardID}/teams/{teamID}](https://docs.evohub.io/board/unshare-board-from-team.md): Take a board back from a team

## Lists

The columns of a board, and the part each plays in review.

- [GET /api/v1/board/boards/{boardID}/lists](https://docs.evohub.io/board/get-board-content.md): List a board's lists and cards
- [POST /api/v1/board/boards/{boardID}/lists](https://docs.evohub.io/board/create-list.md): Create a list
- [DELETE /api/v1/board/lists/{listID}](https://docs.evohub.io/board/archive-list.md): Archive a list
- [PATCH /api/v1/board/lists/{listID}](https://docs.evohub.io/board/rename-list.md): Rename a list
- [POST /api/v1/board/lists/{listID}/move](https://docs.evohub.io/board/move-list.md): Move a list
- [PUT /api/v1/board/lists/{listID}/flags](https://docs.evohub.io/board/set-list-flags.md): Set a list's review and done flags
- [PUT /api/v1/board/lists/{listID}/celebration](https://docs.evohub.io/board/set-list-celebration.md): Set a list's celebration

## Cards

Create, read, edit, move and archive cards.

- [GET /api/v1/board/lists/{listID}/cards](https://docs.evohub.io/board/list-cards.md): List a list's cards
- [POST /api/v1/board/lists/{listID}/cards](https://docs.evohub.io/board/create-card.md): Create a card
- [GET /api/v1/board/cards/{cardID}](https://docs.evohub.io/board/get-card.md): Get a card
- [DELETE /api/v1/board/cards/{cardID}](https://docs.evohub.io/board/archive-card.md): Archive a card
- [PATCH /api/v1/board/cards/{cardID}](https://docs.evohub.io/board/update-card.md): Edit a card's title or description
- [PUT /api/v1/board/cards/{cardID}/color](https://docs.evohub.io/board/set-card-color.md): Set a card's colour
- [POST /api/v1/board/cards/{cardID}/move](https://docs.evohub.io/board/move-card.md): Move a card

## Card details

Assignees, due dates, labels, checklists and comments.

- [GET /api/v1/board/boards/{boardID}/labels](https://docs.evohub.io/board/list-labels.md): List a board's labels
- [POST /api/v1/board/boards/{boardID}/labels](https://docs.evohub.io/board/create-label.md): Create a label
- [DELETE /api/v1/board/boards/{boardID}/labels/{labelID}](https://docs.evohub.io/board/delete-label.md): Delete a label
- [GET /api/v1/board/cards/{cardID}/detail](https://docs.evohub.io/board/get-card-detail.md): Get a card's details
- [POST /api/v1/board/cards/{cardID}/assignees](https://docs.evohub.io/board/assign-card.md): Assign a person to a card
- [DELETE /api/v1/board/cards/{cardID}/assignees/{userID}](https://docs.evohub.io/board/unassign-card.md): Take a person off a card
- [PUT /api/v1/board/cards/{cardID}/due](https://docs.evohub.io/board/set-card-due.md): Set a card's due date
- [PUT /api/v1/board/cards/{cardID}/labels/{labelID}](https://docs.evohub.io/board/add-card-label.md): Label a card
- [DELETE /api/v1/board/cards/{cardID}/labels/{labelID}](https://docs.evohub.io/board/remove-card-label.md): Remove a label from a card
- [POST /api/v1/board/cards/{cardID}/checklist](https://docs.evohub.io/board/add-checklist-item.md): Add a checklist item
- [POST /api/v1/board/cards/{cardID}/comments](https://docs.evohub.io/board/add-comment.md): Comment on a card
- [DELETE /api/v1/board/checklist-items/{itemID}](https://docs.evohub.io/board/delete-checklist-item.md): Delete a checklist item
- [PATCH /api/v1/board/checklist-items/{itemID}](https://docs.evohub.io/board/update-checklist-item.md): Update a checklist item
- [DELETE /api/v1/board/comments/{commentID}](https://docs.evohub.io/board/delete-comment.md): Delete a comment
- [PATCH /api/v1/board/comments/{commentID}](https://docs.evohub.io/board/edit-comment.md): Edit a comment

## Links

Links from a card to things in other EvoHub products.

- [GET /api/v1/board/cards/{cardID}/links](https://docs.evohub.io/board/list-card-links.md): List a card's links
- [POST /api/v1/board/cards/{cardID}/links](https://docs.evohub.io/board/add-card-link.md): Link a card to something
- [DELETE /api/v1/board/links/{linkID}](https://docs.evohub.io/board/remove-card-link.md): Remove a link

## Review

Approve or reject cards waiting for review, and the cards waiting for you.

- [GET /api/v1/board/review-queue](https://docs.evohub.io/board/list-review-queue.md): List cards waiting for your review
- [POST /api/v1/board/cards/{cardID}/approve](https://docs.evohub.io/board/approve-card.md): Approve a card
- [POST /api/v1/board/cards/{cardID}/reject](https://docs.evohub.io/board/reject-card.md): Reject a card

## Archive

Cards that have left a board, and putting them back.

- [GET /api/v1/board/boards/{boardID}/archive](https://docs.evohub.io/board/list-archived-cards.md): List a board's archived cards
- [GET /api/v1/board/archive/cards/{cardID}](https://docs.evohub.io/board/get-archived-card.md): Get an archived card
- [POST /api/v1/board/archive/cards/{cardID}/restore](https://docs.evohub.io/board/restore-archived-card.md): Restore an archived card

## Activity

What happened on a card, and on every board you can see.

- [GET /api/v1/board/activity](https://docs.evohub.io/board/list-board-activity.md): List activity across boards
- [GET /api/v1/board/cards/{cardID}/history](https://docs.evohub.io/board/get-card-history.md): Get a card's history

## Analytics

Throughput, cycle time, work in progress and review figures across your boards.

- [GET /api/v1/board/analytics](https://docs.evohub.io/board/get-board-analytics.md): Get board analytics