# Retro API

Version 1.0 · OpenAPI 3.1.0

Run EvoHub Retro from scripts and integrations: create retro boards, shape
their columns, add and moderate cards, vote, react and comment, track
action items, control a board's shared timer and sharing, export a board
to PDF, and read retro analytics and the audit log.

**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:
it is never treated as an administrator. See the
[API overview](/api-overview), [API keys and scopes](/api-keys-and-scopes)
and [Errors](/errors).

**Responses.** A successful answer carries `"success": true` and its
result in `data`. Errors carry `"success": false` and an `error` object
with a machine-readable `code` and, usually, the `request_id` to quote to
support. Timestamps are RFC 3339 in UTC.

**Who sees a board.** A board belongs to the whole organization
(`team_id` is `""`) or to one team, and its `visibility` says who sees it
without being named on it: `org` (everyone), `team` (that team) or
`private` (nobody). People named on a board, and teams the board was
shared with, see it whatever its visibility. An organization key sees as
its team; a personal key sees as the person who made it. A board the
caller cannot see answers **404** `NOT_FOUND`, exactly like one that does
not exist.

**Closed boards.** Closing a retro freezes it: columns, cards, comments,
reactions, votes, action items and the timer can no longer be changed,
and those writes answer **409** `BOARD_CLOSED`. A closed board can still
be read, renamed, reconfigured, reshared, reopened and deleted.

**Anonymity.** Cards and comments never say who wrote them. The author is
kept only to decide who may edit or delete them: content a key writes is
the key's own (a personal key's is its person's), and changing anyone
else's needs `retro:board:write`.

**Share links.** Guests who open a board's share link use the board
through the web app, with the link as their credential. This reference is
for API-key callers; see [Retro boards](/retro-boards) for share links.

## 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, list, read, change, close, reopen and delete retro boards.

- [GET /api/v1/retro/boards](https://docs.evohub.io/retro/list-retro-boards.md): List boards
- [POST /api/v1/retro/boards](https://docs.evohub.io/retro/create-retro-board.md): Create a board
- [GET /api/v1/retro/boards/{boardID}](https://docs.evohub.io/retro/get-retro-board.md): Get a board
- [DELETE /api/v1/retro/boards/{boardID}](https://docs.evohub.io/retro/delete-retro-board.md): Delete a board
- [PATCH /api/v1/retro/boards/{boardID}](https://docs.evohub.io/retro/update-retro-board.md): Rename or move a board
- [POST /api/v1/retro/boards/{boardID}/close](https://docs.evohub.io/retro/close-retro-board.md): Close a board
- [POST /api/v1/retro/boards/{boardID}/reopen](https://docs.evohub.io/retro/reopen-retro-board.md): Reopen a board

## Sharing

The people and teams a board is shared with, and its share link.

- [GET /api/v1/retro/boards/{boardID}/members](https://docs.evohub.io/retro/list-retro-board-members.md): List who a board is shared with
- [POST /api/v1/retro/boards/{boardID}/members](https://docs.evohub.io/retro/add-retro-board-member.md): Add a person to a board
- [DELETE /api/v1/retro/boards/{boardID}/members/{userID}](https://docs.evohub.io/retro/remove-retro-board-member.md): Remove a person from a board
- [PATCH /api/v1/retro/boards/{boardID}/share](https://docs.evohub.io/retro/update-retro-share-mode.md): Set the share mode
- [POST /api/v1/retro/boards/{boardID}/share/rotate](https://docs.evohub.io/retro/rotate-retro-share-token.md): Rotate the share link
- [POST /api/v1/retro/boards/{boardID}/teams](https://docs.evohub.io/retro/share-retro-board-with-team.md): Share a board with a team
- [DELETE /api/v1/retro/boards/{boardID}/teams/{teamID}](https://docs.evohub.io/retro/unshare-retro-board-from-team.md): Stop sharing a board with a team

## Facilitation

A board's settings and its shared countdown timer.

- [PATCH /api/v1/retro/boards/{boardID}/settings](https://docs.evohub.io/retro/update-retro-board-settings.md): Change a board's settings
- [POST /api/v1/retro/boards/{boardID}/timer](https://docs.evohub.io/retro/control-retro-timer.md): Control the board's timer

## Columns

The columns that give a board its shape.

- [POST /api/v1/retro/boards/{boardID}/columns](https://docs.evohub.io/retro/create-retro-column.md): Add a column
- [DELETE /api/v1/retro/boards/{boardID}/columns/{columnID}](https://docs.evohub.io/retro/delete-retro-column.md): Delete a column
- [PATCH /api/v1/retro/boards/{boardID}/columns/{columnID}](https://docs.evohub.io/retro/update-retro-column.md): Change a column

## Cards

Cards, and the comments, reactions and votes on them.

- [POST /api/v1/retro/boards/{boardID}/cards/merge](https://docs.evohub.io/retro/merge-retro-cards.md): Merge cards
- [DELETE /api/v1/retro/boards/{boardID}/cards/{cardID}](https://docs.evohub.io/retro/delete-retro-card.md): Delete a card
- [PATCH /api/v1/retro/boards/{boardID}/cards/{cardID}](https://docs.evohub.io/retro/update-retro-card.md): Edit a card
- [POST /api/v1/retro/boards/{boardID}/cards/{cardID}/comments](https://docs.evohub.io/retro/create-retro-comment.md): Comment on a card
- [DELETE /api/v1/retro/boards/{boardID}/cards/{cardID}/comments/{commentID}](https://docs.evohub.io/retro/delete-retro-comment.md): Delete a comment
- [POST /api/v1/retro/boards/{boardID}/cards/{cardID}/reactions](https://docs.evohub.io/retro/toggle-retro-reaction.md): Add or remove a reaction
- [POST /api/v1/retro/boards/{boardID}/cards/{cardID}/votes](https://docs.evohub.io/retro/vote-on-retro-card.md): Vote on a card
- [POST /api/v1/retro/boards/{boardID}/columns/{columnID}/cards](https://docs.evohub.io/retro/create-retro-card.md): Add a card

## Action items

What the team agreed to do, with owners and due dates.

- [GET /api/v1/retro/action-items/mine](https://docs.evohub.io/retro/list-my-action-items.md): List my open action items
- [GET /api/v1/retro/boards/{boardID}/action-items](https://docs.evohub.io/retro/list-retro-action-items.md): List a board's action items
- [POST /api/v1/retro/boards/{boardID}/action-items](https://docs.evohub.io/retro/create-retro-action-item.md): Add an action item
- [DELETE /api/v1/retro/boards/{boardID}/action-items/{itemID}](https://docs.evohub.io/retro/delete-retro-action-item.md): Delete an action item
- [PATCH /api/v1/retro/boards/{boardID}/action-items/{itemID}](https://docs.evohub.io/retro/update-retro-action-item.md): Update an action item

## Export

A board as a PDF.

- [GET /api/v1/retro/boards/{boardID}/export](https://docs.evohub.io/retro/export-retro-board.md): Export a board as PDF

## Analytics

Summary counts and retro analytics across the boards you can see.

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

## Audit log

Who changed what in Retro.

- [GET /api/v1/retro/audit-logs](https://docs.evohub.io/retro/list-retro-audit-logs.md): List audit log entries