Quick start
Every path below is relative to this base URL:
https://api.listspace.app/v1Create a token in Settings, then API (see Authentication), and list your boards:
TOKEN=ls_your_token
API=https://api.listspace.app/v1
curl -H "Authorization: Bearer $TOKEN" "$API/boards"The examples on this page use $TOKEN and $API as set here. Want an AI assistant instead of a script? See Use ListSpace from AI assistants.
Authentication
Every request carries a personal API token. Sign in, open Settings, then API, give the token a name and pick its access:
Read only
readList and read boards, lists, cards and labels, and search.
Read and write
read,writeAlso create and rename lists, create, update, move and archive cards, and add checklist items.
A token is ls_ followed by 43 characters. It is shown once. ListSpace stores only its SHA-256 hash and a short prefix, which is how you recognise it in the list. You can have 10 active tokens. Revoke a token in the same place and it stops working at once. Send it in the Authorization header:
Authorization: Bearer ls_your_tokenConventions
- JSON in, JSON out. Field names are
snake_case, ids are UUIDs and dates areYYYY-MM-DD. - A success is
{ "data": ... }. Lists addnext_cursor(see Pagination). - Query values
trueandfalseare booleans. An unknown field or query parameter is an error, so a typo does not go unnoticed. - Card descriptions are markdown by default (
"description_format": "markdown"), or plain text with"text". The markdown can have paragraphs,#headings,-and1.lists,>quotes, fenced code,**bold**,*italic*,`code`,~~strike~~and[links](https://...). HTML in the input shows as text and never runs. - Cards come back with
descriptionas markdown anddescription_htmlas the app stores it, without images.
Pagination
Endpoints that return lists take limit and cursor and answer with next_cursor. Pass it back as cursor to get the next page. null means there is nothing more. Treat a cursor as an opaque string.
curl -H "Authorization: Bearer $TOKEN" "$API/boards?limit=50"
# "next_cursor": "bzo1MA" in the response, so there is more:
curl -H "Authorization: Bearer $TOKEN" "$API/boards?limit=50&cursor=bzo1MA"Errors
A failure has the HTTP status and a body with a stable code and a message you can show:
{
"error": {
"code": "insufficient_scope",
"message": "This API token is read-only. Create a token with write access in Settings > API to make changes."
}
}400
invalid_requestBad JSON, a missing or invalid field, or an unknown field or query parameter. Typos are errors, not ignored.
401
unauthorizedNo token, a malformed token, or a revoked one.
403
insufficient_scopeA change made with a read-only token.
404
not_foundThe item does not exist or is someone else's. The two look the same on purpose.
405
method_not_allowedThe wrong method for this path. The
Allowheader lists the right one.409
conflictSomething else moved the card at the same moment. Try again.
429
rate_limitedMore than 120 requests a minute on one token. Wait the seconds in
Retry-After.500
internalOur fault. The details go to our logs, not into the response.
Rate limits and sizes
- 120 requests a minute per token. Over that, the answer is
429with aRetry-Afterheader in seconds. - Request bodies up to 128 KB.
- Card descriptions up to 20,000 characters, card titles up to 500, list titles up to 200, checklist items up to 1,000.
- Up to 50 labels on a card.
GET /boards/{board_id}returns at most 1,000 cards.
Boards and lists
/boardsList boardsread
Your boards, newest first.
Parameters
include_archivedboolean, in query- Include archived boards. Default
false. limitinteger, in query- How many results to return, 1 to 100. Default 50.
cursorstring, in query- The
next_cursorof the previous page, to get the next one.
curl -H "Authorization: Bearer $TOKEN" "$API/boards?limit=20"{
"data": [
{
"id": "a3f1c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b",
"title": "Home",
"description": "",
"archived": false,
"created_at": "2026-09-14T08:12:40.512345+00:00",
"updated_at": "2026-10-01T17:03:11.208431+00:00",
"url": "https://listspace.app/board/a3f1c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b"
}
],
"next_cursor": null
}/boards/{board_id}Get a boardread
One board with its lists in order, each with its cards, plus the labels those cards use.
Parameters
board_iduuid, in pathrequired- The board.
include_archivedboolean, in query- Include archived lists and cards. Default
false.
- Cards here have no description. Fetch a card with
GET /cards/{card_id}for that. - A board with more than 1,000 cards returns the first 1,000 and
"truncated": true.
curl -H "Authorization: Bearer $TOKEN" "$API/boards/a3f1c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b"{
"data": {
"id": "a3f1c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b",
"title": "Home",
"description": "",
"archived": false,
"created_at": "2026-09-14T08:12:40.512345+00:00",
"updated_at": "2026-10-01T17:03:11.208431+00:00",
"url": "https://listspace.app/board/a3f1c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b",
"lists": [
{
"id": "b4e2d3c5-6a7f-4081-9bac-1d2e3f4a5b6c",
"board_id": "a3f1c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b",
"title": "To do",
"position": 0,
"archived": false,
"cards": [
{
"id": "d6a4f5e7-8c91-42a3-bdce-3f4a5b6c7d8e",
"board_id": "a3f1c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b",
"list_id": "b4e2d3c5-6a7f-4081-9bac-1d2e3f4a5b6c",
"title": "Call the plumber",
"position": 0,
"archived": false,
"due_date": "2026-10-20",
"done": false,
"label_ids": [
"f8c6b7a9-aeb3-44c5-8fe0-5b6c7d8e9fa0"
],
"created_at": "2026-10-02T09:30:00.104512+00:00",
"updated_at": "2026-10-02T09:30:00.104512+00:00",
"url": "https://listspace.app/board/a3f1c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b/card/d6a4f5e7-8c91-42a3-bdce-3f4a5b6c7d8e"
}
]
},
{
"id": "c5f3e4d6-7b80-4192-acbd-2e3f4a5b6c7d",
"board_id": "a3f1c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b",
"title": "Doing",
"position": 1,
"archived": false,
"cards": []
}
],
"labels": [
{
"id": "f8c6b7a9-aeb3-44c5-8fe0-5b6c7d8e9fa0",
"name": "Home",
"color": "green"
}
],
"truncated": false
}
}/boards/{board_id}/listsCreate a listneeds write access
Adds a list at the end of a board.
Parameters
board_iduuid, in pathrequired- The board to add the list to.
titlestring, in bodyrequired- The list title, 1 to 200 characters.
- An archived board is refused with
400. Restore it in the app first.
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"title":"Doing"}' \
"$API/boards/a3f1c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b/lists"{
"data": {
"id": "c5f3e4d6-7b80-4192-acbd-2e3f4a5b6c7d",
"board_id": "a3f1c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b",
"title": "Doing",
"position": 1,
"archived": false
}
}/lists/{list_id}Rename a listneeds write access
Gives a list a new title.
Parameters
list_iduuid, in pathrequired- The list to rename.
titlestring, in bodyrequired- The new title, 1 to 200 characters.
curl -X PATCH -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"title":"In progress"}' \
"$API/lists/c5f3e4d6-7b80-4192-acbd-2e3f4a5b6c7d"{
"data": {
"id": "c5f3e4d6-7b80-4192-acbd-2e3f4a5b6c7d",
"board_id": "a3f1c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b",
"title": "In progress",
"position": 1,
"archived": false
}
}Cards
/cardsList cardsread
The cards of one board or one list, in board order.
Parameters
board_iduuid, in query- All cards on this board. Give
board_idorlist_id, not both. list_iduuid, in query- The cards of this list.
include_archivedboolean, in query- Include archived cards. Default
false. limitinteger, in query- How many results to return, 1 to 200. Default 100.
cursorstring, in query- The
next_cursorof the previous page, to get the next one.
curl -H "Authorization: Bearer $TOKEN" "$API/cards?list_id=b4e2d3c5-6a7f-4081-9bac-1d2e3f4a5b6c"{
"data": [
{
"id": "d6a4f5e7-8c91-42a3-bdce-3f4a5b6c7d8e",
"board_id": "a3f1c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b",
"list_id": "b4e2d3c5-6a7f-4081-9bac-1d2e3f4a5b6c",
"title": "Call the plumber",
"position": 0,
"archived": false,
"due_date": "2026-10-20",
"done": false,
"label_ids": [
"f8c6b7a9-aeb3-44c5-8fe0-5b6c7d8e9fa0"
],
"created_at": "2026-10-02T09:30:00.104512+00:00",
"updated_at": "2026-10-02T09:30:00.104512+00:00",
"url": "https://listspace.app/board/a3f1c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b/card/d6a4f5e7-8c91-42a3-bdce-3f4a5b6c7d8e"
}
],
"next_cursor": null
}/cards/dueList due cardsread
Cards with a due date across all your boards, soonest first. Archived cards, lists and boards are left out.
Parameters
fromdate, in query- Only cards due on or after this date (
YYYY-MM-DD). todate, in query- Only cards due on or before this date.
include_doneboolean, in query- Include cards whose due date is marked done. Default
false. limitinteger, in query- How many results to return, 1 to 200. Default 50.
cursorstring, in query- The
next_cursorof the previous page, to get the next one.
- A
fromaftertois refused with400.
curl -H "Authorization: Bearer $TOKEN" "$API/cards/due?from=2026-10-19&to=2026-10-25"{
"data": [
{
"id": "d6a4f5e7-8c91-42a3-bdce-3f4a5b6c7d8e",
"board_id": "a3f1c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b",
"list_id": "b4e2d3c5-6a7f-4081-9bac-1d2e3f4a5b6c",
"title": "Call the plumber",
"position": 0,
"archived": false,
"due_date": "2026-10-20",
"done": false,
"label_ids": [
"f8c6b7a9-aeb3-44c5-8fe0-5b6c7d8e9fa0"
],
"created_at": "2026-10-02T09:30:00.104512+00:00",
"updated_at": "2026-10-02T09:30:00.104512+00:00",
"url": "https://listspace.app/board/a3f1c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b/card/d6a4f5e7-8c91-42a3-bdce-3f4a5b6c7d8e"
}
],
"next_cursor": null
}/cards/{card_id}Get a cardread
One card in full: description, labels and checklists.
Parameters
card_iduuid, in pathrequired- The card.
descriptionis markdown.description_htmlis the description as the app stores it, without images (they point at private storage).
curl -H "Authorization: Bearer $TOKEN" "$API/cards/d6a4f5e7-8c91-42a3-bdce-3f4a5b6c7d8e"{
"data": {
"id": "d6a4f5e7-8c91-42a3-bdce-3f4a5b6c7d8e",
"board_id": "a3f1c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b",
"list_id": "b4e2d3c5-6a7f-4081-9bac-1d2e3f4a5b6c",
"title": "Call the plumber",
"position": 0,
"archived": false,
"due_date": "2026-10-20",
"done": false,
"label_ids": [
"f8c6b7a9-aeb3-44c5-8fe0-5b6c7d8e9fa0"
],
"created_at": "2026-10-02T09:30:00.104512+00:00",
"updated_at": "2026-10-02T09:30:00.104512+00:00",
"url": "https://listspace.app/board/a3f1c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b/card/d6a4f5e7-8c91-42a3-bdce-3f4a5b6c7d8e",
"description": "Ask about the **kitchen** tap",
"description_html": "<p>Ask about the <strong>kitchen</strong> tap</p>",
"labels": [
{
"id": "f8c6b7a9-aeb3-44c5-8fe0-5b6c7d8e9fa0",
"name": "Home",
"color": "green"
}
],
"checklists": [
{
"id": "09d7c8ba-bfc4-45d6-90f1-6c7d8e9fa0b1",
"title": "Checklist",
"items": [
{
"id": "1ae8d9cb-c0d5-46e7-a102-7d8e9fa0b1c2",
"text": "Find the receipt",
"done": false
}
]
}
]
}
}/cardsCreate a cardneeds write access
Adds a card to a list and returns it.
Parameters
list_iduuid, in bodyrequired- The list to add the card to.
titlestring, in bodyrequired- The card title, 1 to 500 characters.
descriptionstring, in body- The card description, at most 20,000 characters. Markdown unless
description_formatsaystext. description_formatstring, in bodymarkdown(default) ortext, which keeps the description as typed.due_datedate or null, in body- Due date as
YYYY-MM-DD. label_idsuuid[], in body- Label ids from
GET /labels, at most 50, no repeats. positionstring, in bodytoporbottom(default) of the list.
- An archived list or board is refused with
400. - Label ids are checked before anything is written, so an unknown label id leaves no half-made card.
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"list_id":"b4e2d3c5-6a7f-4081-9bac-1d2e3f4a5b6c","title":"Call the plumber","description":"Ask about the **kitchen** tap","due_date":"2026-10-20","label_ids":["f8c6b7a9-aeb3-44c5-8fe0-5b6c7d8e9fa0"]}' \
"$API/cards"{
"data": {
"id": "d6a4f5e7-8c91-42a3-bdce-3f4a5b6c7d8e",
"board_id": "a3f1c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b",
"list_id": "b4e2d3c5-6a7f-4081-9bac-1d2e3f4a5b6c",
"title": "Call the plumber",
"position": 0,
"archived": false,
"due_date": "2026-10-20",
"done": false,
"label_ids": [
"f8c6b7a9-aeb3-44c5-8fe0-5b6c7d8e9fa0"
],
"created_at": "2026-10-02T09:30:00.104512+00:00",
"updated_at": "2026-10-02T09:30:00.104512+00:00",
"url": "https://listspace.app/board/a3f1c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b/card/d6a4f5e7-8c91-42a3-bdce-3f4a5b6c7d8e",
"description": "Ask about the **kitchen** tap",
"description_html": "<p>Ask about the <strong>kitchen</strong> tap</p>",
"labels": [
{
"id": "f8c6b7a9-aeb3-44c5-8fe0-5b6c7d8e9fa0",
"name": "Home",
"color": "green"
}
],
"checklists": []
}
}/cards/{card_id}Update a cardneeds write access
Changes only the fields you send. Send at least one.
Parameters
card_iduuid, in pathrequired- The card to change.
titlestring, in body- The new title, 1 to 500 characters.
descriptionstring, in body- Replaces the description. Markdown unless
description_formatsaystext. description_formatstring, in bodymarkdown(default) ortext, which keeps the description as typed.due_datedate or null, in bodyYYYY-MM-DD, ornullto remove the due date together with its done tick and due time.doneboolean, in body- Marks the due date as met (
true) or not (false). label_idsuuid[], in body- Replaces the whole set of labels. At most 50.
done: trueneeds a due date, because in ListSpace "done" marks a due date as met.- A due date before the card's start date moves the start date to it, as in the app.
curl -X PATCH -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"due_date":"2026-10-22"}' \
"$API/cards/d6a4f5e7-8c91-42a3-bdce-3f4a5b6c7d8e"{
"data": {
"id": "d6a4f5e7-8c91-42a3-bdce-3f4a5b6c7d8e",
"board_id": "a3f1c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b",
"list_id": "b4e2d3c5-6a7f-4081-9bac-1d2e3f4a5b6c",
"title": "Call the plumber",
"position": 0,
"archived": false,
"due_date": "2026-10-22",
"done": false,
"label_ids": [
"f8c6b7a9-aeb3-44c5-8fe0-5b6c7d8e9fa0"
],
"created_at": "2026-10-02T09:30:00.104512+00:00",
"updated_at": "2026-10-03T14:21:05.770132+00:00",
"url": "https://listspace.app/board/a3f1c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b/card/d6a4f5e7-8c91-42a3-bdce-3f4a5b6c7d8e",
"description": "Ask about the **kitchen** tap",
"description_html": "<p>Ask about the <strong>kitchen</strong> tap</p>",
"labels": [
{
"id": "f8c6b7a9-aeb3-44c5-8fe0-5b6c7d8e9fa0",
"name": "Home",
"color": "green"
}
],
"checklists": []
}
}/cards/{card_id}/moveMove a cardneeds write access
Moves a card to another list, on the same or another board, or reorders it in its list.
Parameters
card_iduuid, in pathrequired- The card to move.
list_iduuid, in body- The target list. Default: the list the card is in.
before_card_iduuid, in body- Place it right before this card of the target list.
positionstring, in body- Or
toporbottom(default) of the list. Givebefore_card_idorposition, not both.
- An archived card cannot be moved until you restore it. An archived list cannot take cards.
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"list_id":"c5f3e4d6-7b80-4192-acbd-2e3f4a5b6c7d","position":"top"}' \
"$API/cards/d6a4f5e7-8c91-42a3-bdce-3f4a5b6c7d8e/move"{
"data": {
"id": "d6a4f5e7-8c91-42a3-bdce-3f4a5b6c7d8e",
"board_id": "a3f1c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b",
"list_id": "c5f3e4d6-7b80-4192-acbd-2e3f4a5b6c7d",
"title": "Call the plumber",
"position": 0,
"archived": false,
"due_date": "2026-10-20",
"done": false,
"label_ids": [
"f8c6b7a9-aeb3-44c5-8fe0-5b6c7d8e9fa0"
],
"created_at": "2026-10-02T09:30:00.104512+00:00",
"updated_at": "2026-10-03T14:25:48.019377+00:00",
"url": "https://listspace.app/board/a3f1c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b/card/d6a4f5e7-8c91-42a3-bdce-3f4a5b6c7d8e",
"description": "Ask about the **kitchen** tap",
"description_html": "<p>Ask about the <strong>kitchen</strong> tap</p>",
"labels": [
{
"id": "f8c6b7a9-aeb3-44c5-8fe0-5b6c7d8e9fa0",
"name": "Home",
"color": "green"
}
],
"checklists": []
}
}/cards/{card_id}/archiveArchive a cardneeds write access
Archives a card, or restores it with "archived": false.
Parameters
card_iduuid, in pathrequired- The card.
archivedboolean, in bodytrue(default) archives,falserestores. The body is optional.
curl -X POST -H "Authorization: Bearer $TOKEN" "$API/cards/d6a4f5e7-8c91-42a3-bdce-3f4a5b6c7d8e/archive"{
"data": {
"id": "d6a4f5e7-8c91-42a3-bdce-3f4a5b6c7d8e",
"board_id": "a3f1c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b",
"list_id": "b4e2d3c5-6a7f-4081-9bac-1d2e3f4a5b6c",
"title": "Call the plumber",
"position": 0,
"archived": true,
"due_date": "2026-10-20",
"done": false,
"label_ids": [
"f8c6b7a9-aeb3-44c5-8fe0-5b6c7d8e9fa0"
],
"created_at": "2026-10-02T09:30:00.104512+00:00",
"updated_at": "2026-10-03T14:30:02.551904+00:00",
"url": "https://listspace.app/board/a3f1c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b/card/d6a4f5e7-8c91-42a3-bdce-3f4a5b6c7d8e",
"description": "Ask about the **kitchen** tap",
"description_html": "<p>Ask about the <strong>kitchen</strong> tap</p>",
"labels": [
{
"id": "f8c6b7a9-aeb3-44c5-8fe0-5b6c7d8e9fa0",
"name": "Home",
"color": "green"
}
],
"checklists": []
}
}/cards/{card_id}/checklist-itemsAdd a checklist itemneeds write access
Adds an item to a checklist on a card and returns the card.
Parameters
card_iduuid, in pathrequired- The card.
textstring, in bodyrequired- The item text, 1 to 1,000 characters.
checklist_iduuid, in body- The checklist to add to. Default: the card's first checklist, created as "Checklist" if the card has none.
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"text":"Find the receipt"}' \
"$API/cards/d6a4f5e7-8c91-42a3-bdce-3f4a5b6c7d8e/checklist-items"{
"data": {
"id": "d6a4f5e7-8c91-42a3-bdce-3f4a5b6c7d8e",
"board_id": "a3f1c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b",
"list_id": "b4e2d3c5-6a7f-4081-9bac-1d2e3f4a5b6c",
"title": "Call the plumber",
"position": 0,
"archived": false,
"due_date": "2026-10-20",
"done": false,
"label_ids": [
"f8c6b7a9-aeb3-44c5-8fe0-5b6c7d8e9fa0"
],
"created_at": "2026-10-02T09:30:00.104512+00:00",
"updated_at": "2026-10-02T09:30:00.104512+00:00",
"url": "https://listspace.app/board/a3f1c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b/card/d6a4f5e7-8c91-42a3-bdce-3f4a5b6c7d8e",
"description": "Ask about the **kitchen** tap",
"description_html": "<p>Ask about the <strong>kitchen</strong> tap</p>",
"labels": [
{
"id": "f8c6b7a9-aeb3-44c5-8fe0-5b6c7d8e9fa0",
"name": "Home",
"color": "green"
}
],
"checklists": [
{
"id": "09d7c8ba-bfc4-45d6-90f1-6c7d8e9fa0b1",
"title": "Checklist",
"items": [
{
"id": "1ae8d9cb-c0d5-46e7-a102-7d8e9fa0b1c2",
"text": "Find the receipt",
"done": false
}
]
}
]
}
}Search and labels
/searchSearch cardsread
Cards whose title or description contain every word of the query. Word beginnings count, so "plan" finds "planning".
Parameters
querystring, in queryrequired- The words to find, 1 to 200 characters.
limitinteger, in query- How many results to return, 1 to 50. Default 20.
cursorstring, in query- The
next_cursorof the previous page, to get the next one.
- The response adds
total, the number of matching cards.
curl -H "Authorization: Bearer $TOKEN" "$API/search?query=plumber"{
"total": 1,
"data": [
{
"id": "d6a4f5e7-8c91-42a3-bdce-3f4a5b6c7d8e",
"title": "Call the plumber",
"snippet": "Ask about the kitchen tap",
"board_id": "a3f1c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b",
"board_title": "Home",
"list_id": "b4e2d3c5-6a7f-4081-9bac-1d2e3f4a5b6c",
"list_title": "To do",
"url": "https://listspace.app/board/a3f1c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b/card/d6a4f5e7-8c91-42a3-bdce-3f4a5b6c7d8e"
}
],
"next_cursor": null
}/labelsList labelsread
Your labels with their ids, for label_ids on cards.
curl -H "Authorization: Bearer $TOKEN" "$API/labels"{
"data": [
{
"id": "f8c6b7a9-aeb3-44c5-8fe0-5b6c7d8e9fa0",
"name": "Home",
"color": "green"
}
]
}