Rob Zolkos
cdd13c1a61
* Split docs/API.md into per-resource sections under docs/api/ * Move API endpoints index above authentication in docs/api/README.md * Fix trailing comma in boards.md JSON example * Fix trailing comma in cards.md, add Response label to identity.md, add Rich Text to endpoint index
4.8 KiB
Boards
Boards are where you organize your work - they contain your cards.
GET /:account_slug/boards
Returns a list of boards that you can access in the specified account.
Response:
[
{
"id": "03f5v9zkft4hj9qq0lsn9ohcm",
"name": "Fizzy",
"all_access": true,
"created_at": "2025-12-05T19:36:35.534Z",
"auto_postpone_period_in_days": 30,
"url": "http://fizzy.localhost:3006/897362094/boards/03f5v9zkft4hj9qq0lsn9ohcm",
"creator": {
"id": "03f5v9zjw7pz8717a4no1h8a7",
"name": "David Heinemeier Hansson",
"role": "owner",
"active": true,
"email_address": "david@example.com",
"created_at": "2025-12-05T19:36:35.401Z",
"url": "http://fizzy.localhost:3006/897362094/users/03f5v9zjw7pz8717a4no1h8a7"
}
}
]
GET /:account_slug/boards/:board_id
Returns the specified board.
Response:
{
"id": "03f5v9zkft4hj9qq0lsn9ohcm",
"name": "Fizzy",
"all_access": true,
"created_at": "2025-12-05T19:36:35.534Z",
"auto_postpone_period_in_days": 30,
"url": "http://fizzy.localhost:3006/897362094/boards/03f5v9zkft4hj9qq0lsn9ohcm",
"creator": {
"id": "03f5v9zjw7pz8717a4no1h8a7",
"name": "David Heinemeier Hansson",
"role": "owner",
"active": true,
"email_address": "david@example.com",
"created_at": "2025-12-05T19:36:35.401Z",
"url": "http://fizzy.localhost:3006/897362094/users/03f5v9zjw7pz8717a4no1h8a7"
},
"public_url": "http://fizzy.localhost:3006/897362094/public/boards/aB3dEfGhIjKlMnOp"
}
The public_url field is only present when the board is published.
POST /:account_slug/boards
Creates a new Board in the account.
| Parameter | Type | Required | Description |
|---|---|---|---|
name |
string | Yes | The name of the board |
all_access |
boolean | No | Whether any user in the account can access this board. Defaults to true |
auto_postpone_period_in_days |
integer | No | Number of days of inactivity before cards are automatically postponed (e.g. 30) |
public_description |
string | No | Rich text description shown on the public board page |
Request:
{
"board": {
"name": "My new board"
}
}
Response:
Returns 201 Created with a Location header pointing to the new board:
HTTP/1.1 201 Created
Location: /897362094/boards/03f5v9zkft4hj9qq0lsn9ohcm.json
PUT /:account_slug/boards/:board_id
Updates a Board. Only board administrators can update a board.
| Parameter | Type | Required | Description |
|---|---|---|---|
name |
string | No | The name of the board |
all_access |
boolean | No | Whether any user in the account can access this board |
auto_postpone_period_in_days |
integer | No | Number of days of inactivity before cards are automatically postponed (e.g. 30) |
public_description |
string | No | Rich text description shown on the public board page |
user_ids |
array | No | Array of all user IDs who should have access to this board (only applicable when all_access is false) |
Request:
{
"board": {
"name": "Updated board name",
"auto_postpone_period_in_days": 30,
"public_description": "This is a **public** description of the board.",
"all_access": false,
"user_ids": [
"03f5v9zppzlksuj4mxba2nbzn",
"03f5v9zjw7pz8717a4no1h8a7"
]
}
}
Response:
Returns 204 No Content on success.
DELETE /:account_slug/boards/:board_id
Deletes a Board. Only board administrators can delete a board.
Response:
Returns 204 No Content on success.
Board Publications
Publishing a board makes it publicly accessible via a shareable link, without requiring authentication. Only board administrators can publish or unpublish a board.
POST /:account_slug/boards/:board_id/publication
Publishes a board, generating a shareable public link.
Response:
HTTP/1.1 201 Created
{
"id": "03f5v9zkft4hj9qq0lsn9ohcm",
"name": "Fizzy",
"all_access": true,
"created_at": "2025-12-05T19:36:35.534Z",
"auto_postpone_period_in_days": 30,
"url": "http://fizzy.localhost:3006/897362094/boards/03f5v9zkft4hj9qq0lsn9ohcm",
"creator": {
"id": "03f5v9zjw7pz8717a4no1h8a7",
"name": "David Heinemeier Hansson",
"role": "owner",
"active": true,
"email_address": "david@example.com",
"created_at": "2025-12-05T19:36:35.401Z",
"url": "http://fizzy.localhost:3006/897362094/users/03f5v9zjw7pz8717a4no1h8a7"
},
"public_url": "http://fizzy.localhost:3006/897362094/public/boards/aB3dEfGhIjKlMnOp"
}
If the board is already published, the existing publication is returned.
DELETE /:account_slug/boards/:board_id/publication
Unpublishes a board, removing public access.
Response:
Returns 204 No Content on success.