REST API

The cookie-authenticated HTTP API shared by the web app and the MCP server, with every endpoint.

The web app and the MCP server both use this HTTP API. It is the app's own API, not a separate
public platform: authentication is a session cookie, not an OAuth token.

Base URL

EnvironmentBase URL
Localhttp://localhost:4000/api
Productionhttps://your-domain.example/api

All request and response bodies are JSON. UUIDs are used for every resource ID.

Authentication

Sign in to receive the kanban_session cookie, then send it with every request:

curl -c cookies.txt -X POST http://localhost:4000/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"identifier":"ada","password":"Kanban!Passw0rd"}'

curl -b cookies.txt http://localhost:4000/api/workplaces

The cookie is httpOnly, SameSite=Lax, and lasts seven days. There is no bearer-token flow. The
MCP server signs in the same way and caches the cookie for its own calls.

Errors

Failures return an HTTP status and a consistent body:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input.",
    "fields": {
      "title": ["Card title is required."]
    }
  }
}

Common codes include UNAUTHENTICATED (401), FORBIDDEN (403), NOT_FOUND (404),
CONFLICT (409), VALIDATION_ERROR (400), and RATE_LIMITED (429). Ownership violations return
403; resources from another workplace return 404.

Health

MethodPathDescription
GET/api/healthLiveness check; returns { "ok": true }

Account

MethodPathDescription
POST/api/auth/registerCreate an account and its default workplace
GET/api/auth/availabilityCheck whether a username and/or email is already in use
POST/api/auth/loginSign in with identifier (username or email) and password
POST/api/auth/logoutClear the session cookie
GET/api/auth/meCurrent user and workplaces

Sign-up validation

The web form calls GET /api/auth/availability?username=ada&[email protected] while the user
types. Send at least one field; both are trimmed and lowercased first.

{
  "username": { "available": false, "message": "That username is already taken." },
  "email": { "available": true, "message": null }
}

The response is sent with Cache-Control: no-store and is limited to 60 requests per minute per IP
(429 RATE_LIMITED). Invalid formats and reserved usernames return 400 VALIDATION_ERROR with a
fields map. Availability necessarily reveals whether an account exists — it is a UX aid, not an
authorization check.

Registration enforces the same rules server-side:

  • Username — 3–24 characters of lowercase letters, numbers, and underscores. Leading/trailing
    spaces are trimmed, embedded spaces are rejected, and reserved names (admin, support, api,
    …) are refused.
  • Email — a valid address, at most 254 characters, unique case-insensitively.
  • Password — 8–200 characters with uppercase and lowercase letters, a number, and a symbol. It
    may not be a common password or contain the username or email local-part.
  • Conflicts — a duplicate username or email returns 409 CONFLICT with
    error.fields.username and/or error.fields.email, so the form can highlight the exact input.

Workplaces

MethodPathDescription
GET/api/workplacesWorkplaces you belong to
POST/api/workplacesCreate a workplace with the four default columns
PATCH/api/workplaces/:workplaceIdRename a workplace (owner)
GET/api/workplaces/:workplaceId/boardBoard, columns, tags, cards, and your role
GET/api/workplaces/:workplaceId/membersMembers; emails are visible to the owner
DELETE/api/workplaces/:workplaceId/members/:userIdRemove a member (owner)
POST/api/workplaces/:workplaceId/leaveLeave a workplace (members)

Invitations

MethodPathDescription
GET/api/invitationsPending invitations addressed to you
GET/api/workplaces/:workplaceId/invitationsPending invitations sent by a workplace (owner)
POST/api/workplaces/:workplaceId/invitationsInvite by username or email (owner)
DELETE/api/invitations/:invitationIdCancel a pending invitation (owner)
POST/api/invitations/:invitationId/acceptAccept your invitation
POST/api/invitations/:invitationId/declineDecline your invitation

Columns

MethodPathDescription
POST/api/workplaces/:workplaceId/columnsAdd a column (owner)
PUT/api/workplaces/:workplaceId/columns/orderReorder every column (owner)
PATCH/api/columns/:columnIdRename or hide a column (owner)
DELETE/api/columns/:columnIdDelete a column; its cards move to the first visible column (owner)

Cards

MethodPathDescription
POST/api/workplaces/:workplaceId/cardsCreate a card
GET/api/cards/:cardIdFull card detail with checklists and comments
PATCH/api/cards/:cardIdChange title or description
PATCH/api/cards/:cardId/moveMove to a column and position
DELETE/api/cards/:cardIdDelete a card and its children
PUT/api/cards/:cardId/tagsReplace the card's tags
PUT/api/cards/:cardId/assigneesReplace the card's assignees

Checklists and comments

MethodPathDescription
POST/api/cards/:cardId/subtasksAdd a checklist item
PATCH/api/subtasks/:subtaskIdRename or toggle a checklist item
DELETE/api/subtasks/:subtaskIdDelete a checklist item
POST/api/cards/:cardId/commentsComment on a card
PATCH/api/comments/:commentIdEdit your own comment
DELETE/api/comments/:commentIdDelete your comment, or any comment as owner

Tags

MethodPathDescription
GET/api/workplaces/:workplaceId/tagsList tags
POST/api/workplaces/:workplaceId/tagsCreate a tag
PATCH/api/tags/:tagIdRename or recolor a tag (owner)
DELETE/api/tags/:tagIdDelete a tag everywhere (owner)

Working with the API from an AI client

The MCP server wraps this API with 39 tools, so an AI client does not need to build
requests or manage the cookie itself. Use the REST API directly when you are writing your own
integration.


Did this page help you?