Kanban API

Use the API to read and write the data of one team from your own scripts. The API sends and takes JSON. The base address is https://kanban.utilarium.app/api/v1.

There is also an OpenAPI 3.1 file for your tools.

Authentication

The owner of a team makes an API key in Kanban, in Settings under API keys. A team can have 20 keys. Kanban shows the secret one time. Keep it private. Each key works for one team only.

Send the secret in the Authorization header of each request. A secret is kanban_ and 40 hex characters.

curl "https://kanban.utilarium.app/api/v1/boards?limit=10" \
  -H "Authorization: Bearer $KANBAN_API_KEY"

Open Kanban to make a key.

Records and pages

Field names use camelCase. A list answers with data and nextCursor. A page has 50 records. Use limit to ask for up to 200. When nextCursor is not null, send it as cursor to get the next page. One record answers with data.

{ "data": [ { "id": "…", "title": "Write the home page" } ], "nextCursor": "1700000000000~abc" }

The q parameter of the card list searches. Each word must have 3 letters or more, and must be inside the title, the description or the labels. A time is in milliseconds since 1970. To add a card, read the lists of a board, then send POST /cards with a listId. To move a card, send POST /cards/{id}/move with a listId. To add a file, send the raw file as the body of POST /cards/{id}/files?name=…, with a Content-Length header.

Boards and lists

`GET /boards`

List boards.

archived:: true, false (default) or all.
limit:: From 1 to 200. Default 50.
cursor:: The nextCursor of the last page.

curl "https://kanban.utilarium.app/api/v1/boards?limit=10" \
  -H "Authorization: Bearer $KANBAN_API_KEY"

`POST /boards`

Make one of boards.

Body fields: name, description, archived.

curl -X POST "https://kanban.utilarium.app/api/v1/boards" \
  -H "Authorization: Bearer $KANBAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Website","description":"Tasks for the new website"}'

`GET /boards/{id}`

Read one of boards.

curl "https://kanban.utilarium.app/api/v1/boards/ID" \
  -H "Authorization: Bearer $KANBAN_API_KEY"

`PATCH /boards/{id}`

Change one of boards.

Body fields: name, description, archived.

curl -X PATCH "https://kanban.utilarium.app/api/v1/boards/ID" \
  -H "Authorization: Bearer $KANBAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"archived":true}'

`DELETE /boards/{id}`

Delete one of boards.

curl -X DELETE "https://kanban.utilarium.app/api/v1/boards/ID" \
  -H "Authorization: Bearer $KANBAN_API_KEY"

`GET /boards/{id}/lists`

List the lists of a board.

curl "https://kanban.utilarium.app/api/v1/boards/ID/lists" \
  -H "Authorization: Bearer $KANBAN_API_KEY"

`POST /boards/{id}/lists`

Add a list to a board.

Body fields: name (needed).

curl -X POST "https://kanban.utilarium.app/api/v1/boards/ID/lists" \
  -H "Authorization: Bearer $KANBAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Review"}'

`PUT /boards/{id}/lists/order`

Set the order of the lists of a board.

Body fields: ids (needed).

curl -X PUT "https://kanban.utilarium.app/api/v1/boards/ID/lists/order" \
  -H "Authorization: Bearer $KANBAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids":["LIST_ID_1","LIST_ID_2"]}'

`PATCH /boards/{id}/lists/{listId}`

Rename a list.

Body fields: name (needed).

curl -X PATCH "https://kanban.utilarium.app/api/v1/boards/ID/lists/LIST_ID" \
  -H "Authorization: Bearer $KANBAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Ready"}'

`DELETE /boards/{id}/lists/{listId}`

Delete an empty list.

curl -X DELETE "https://kanban.utilarium.app/api/v1/boards/ID/lists/LIST_ID" \
  -H "Authorization: Bearer $KANBAN_API_KEY"

Cards

`GET /cards`

List cards.

boardId:: Cards of one board, in board order.
listId:: Cards of one list, in order.
assignee:: The email of a member.
clientId:: Cards of one client.
projectId:: Cards of one project.
label:: One label.
due_from:: YYYY-MM-DD. Cards due on or after this day, by due date.
due_to:: YYYY-MM-DD. Cards due on or before this day, by due date.
q:: Text inside the title, description or labels. Each word needs 3 letters or more.
limit:: From 1 to 200. Default 50.
cursor:: The nextCursor of the last page.

curl "https://kanban.utilarium.app/api/v1/cards?limit=10" \
  -H "Authorization: Bearer $KANBAN_API_KEY"

`POST /cards`

Make one of cards.

Body fields: listId, boardId, title, description, dueDate, labels, assignee, clientId, projectId, position, done.

curl -X POST "https://kanban.utilarium.app/api/v1/cards" \
  -H "Authorization: Bearer $KANBAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"listId":"LIST_ID","title":"Write the home page","labels":["design"],"dueDate":"2026-12-31"}'

`GET /cards/{id}`

Read one of cards.

curl "https://kanban.utilarium.app/api/v1/cards/ID" \
  -H "Authorization: Bearer $KANBAN_API_KEY"

`PATCH /cards/{id}`

Change one of cards.

Body fields: listId, boardId, title, description, dueDate, labels, assignee, clientId, projectId, position, done.

curl -X PATCH "https://kanban.utilarium.app/api/v1/cards/ID" \
  -H "Authorization: Bearer $KANBAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"done":true}'

`DELETE /cards/{id}`

Delete one of cards.

curl -X DELETE "https://kanban.utilarium.app/api/v1/cards/ID" \
  -H "Authorization: Bearer $KANBAN_API_KEY"

`POST /cards/{id}/move`

Move a card to a list.

Body fields: listId (needed), position.

curl -X POST "https://kanban.utilarium.app/api/v1/cards/ID/move" \
  -H "Authorization: Bearer $KANBAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"listId":"LIST_ID"}'

Comments

`GET /cards/{id}/comments`

List the comments of a card.

limit:: From 1 to 200. Default 50.
cursor:: The nextCursor of the last page.

curl "https://kanban.utilarium.app/api/v1/cards/ID/comments" \
  -H "Authorization: Bearer $KANBAN_API_KEY"

`POST /cards/{id}/comments`

Add a comment to a card.

Body fields: body (needed).

curl -X POST "https://kanban.utilarium.app/api/v1/cards/ID/comments" \
  -H "Authorization: Bearer $KANBAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body":"Done. Please check."}'

`DELETE /cards/{id}/comments/{commentId}`

Delete a comment.

curl -X DELETE "https://kanban.utilarium.app/api/v1/cards/ID/comments/COMMENT_ID" \
  -H "Authorization: Bearer $KANBAN_API_KEY"

Files

`GET /cards/{id}/files`

List the files of a card.

curl "https://kanban.utilarium.app/api/v1/cards/ID/files" \
  -H "Authorization: Bearer $KANBAN_API_KEY"

`POST /cards/{id}/files`

Add a file to a card.

name (needed):: The file name.

curl -X POST "https://kanban.utilarium.app/api/v1/cards/ID/files?name=photo.png" \
  -H "Authorization: Bearer $KANBAN_API_KEY" \
  -H "Content-Type: image/png" \
  --data-binary @photo.png

`GET /files/{id}`

Download a file.

curl "https://kanban.utilarium.app/api/v1/files/ID" \
  -H "Authorization: Bearer $KANBAN_API_KEY"

`DELETE /files/{id}`

Delete a file.

curl -X DELETE "https://kanban.utilarium.app/api/v1/files/ID" \
  -H "Authorization: Bearer $KANBAN_API_KEY"

Clients

`GET /clients`

List clients.

limit:: From 1 to 200. Default 50.
cursor:: The nextCursor of the last page.

curl "https://kanban.utilarium.app/api/v1/clients?limit=10" \
  -H "Authorization: Bearer $KANBAN_API_KEY"

`POST /clients`

Make one of clients.

Body fields: name, email, notes.

curl -X POST "https://kanban.utilarium.app/api/v1/clients" \
  -H "Authorization: Bearer $KANBAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Analytical Engines","email":"ada@example.com"}'

`GET /clients/{id}`

Read one of clients.

curl "https://kanban.utilarium.app/api/v1/clients/ID" \
  -H "Authorization: Bearer $KANBAN_API_KEY"

`PATCH /clients/{id}`

Change one of clients.

Body fields: name, email, notes.

curl -X PATCH "https://kanban.utilarium.app/api/v1/clients/ID" \
  -H "Authorization: Bearer $KANBAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"notes":"Pays in 30 days"}'

`DELETE /clients/{id}`

Delete one of clients.

curl -X DELETE "https://kanban.utilarium.app/api/v1/clients/ID" \
  -H "Authorization: Bearer $KANBAN_API_KEY"

Projects

`GET /projects`

List projects.

clientId:: Projects of one client.
limit:: From 1 to 200. Default 50.
cursor:: The nextCursor of the last page.

curl "https://kanban.utilarium.app/api/v1/projects?limit=10" \
  -H "Authorization: Bearer $KANBAN_API_KEY"

`POST /projects`

Make one of projects.

Body fields: name, clientId, archived.

curl -X POST "https://kanban.utilarium.app/api/v1/projects" \
  -H "Authorization: Bearer $KANBAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Website","clientId":"CLIENT_ID"}'

`GET /projects/{id}`

Read one of projects.

curl "https://kanban.utilarium.app/api/v1/projects/ID" \
  -H "Authorization: Bearer $KANBAN_API_KEY"

`PATCH /projects/{id}`

Change one of projects.

Body fields: name, clientId, archived.

curl -X PATCH "https://kanban.utilarium.app/api/v1/projects/ID" \
  -H "Authorization: Bearer $KANBAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"archived":true}'

`DELETE /projects/{id}`

Delete one of projects.

curl -X DELETE "https://kanban.utilarium.app/api/v1/projects/ID" \
  -H "Authorization: Bearer $KANBAN_API_KEY"

Errors

An error has a status and a JSON body. The body has a short code and a message to read.

{ "error": { "code": "unauthorized", "message": "The API key is not valid" } }

400 bad_request: The request has a wrong value. Read the message.
401 unauthorized: The API key is missing or not valid.
404 not_found: The record does not exist in the team of the key.
409 conflict: The value is in use already, for example an email address.
413 too_large: The body is too long.
415 unsupported_media_type: Send the body as application/json.
429 limit_reached: A limit is reached. Wait, or read the message.

Limits

A key can make 120 requests each minute. Over that, the API answers 429.
A team can make 20,000 changes each UTC day. The page and the API share this number.
A body can have 1,000,000 characters.
The record limits of the team apply to the API too. Read them on the start page.