david/kanban-app
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
kanban-app/docs/kanban_api.md

9.3 KiB
Raw Blame History

Kanban API Documentation

This document describes all the API endpoints for the Kanban application. All endpoints require authentication unless otherwise noted.

Base URL

http://localhost:5000/api

Authentication

All endpoints (except register and login) require a JWT token in the Authorization header:

Authorization: Bearer <your_jwt_token>

Boards

Get All Boards

GET /api/boards

Get all boards for the current authenticated user.

Response: Array of board objects

Get Single Board

GET /api/boards/<board_id>

Get a board with all its details including lists, cards, and labels.

Response: Board object with nested lists, cards, and labels

Create Board

POST /api/boards

Create a new board.

Request Body:

{
  "name": "My Project Board",
  "description": "Project management board",
  "url": "https://example.com/board/123",
  "short_link": "abc123",
  "short_url": "https://example.com/b/abc123",
  "prefs": {},
  "label_names": {},
  "limits": {}
}

Response: Created board object

Update Board

PUT /api/boards/<board_id>

Update a board.

Request Body: Partial board object (only include fields to update)

Response: Updated board object

Delete Board

DELETE /api/boards/<board_id>

Delete a board and all its associated data.

Response: Success message

Lists

Create List

POST /api/boards/<board_id>/lists

Create a new list in a board.

Request Body:

{
  "name": "To Do",
  "pos": 0
}

Response: Created list object

Update List

PUT /api/lists/<list_id>

Update a list.

Request Body: Partial list object

Response: Updated list object

Delete List

DELETE /api/lists/<list_id>

Delete a list and all its cards.

Response: Success message

Cards

Create Card

POST /api/lists/<list_id>/cards

Create a new card in a list.

Request Body:

{
  "name": "Task Name",
  "description": "Task description",
  "pos": 0,
  "due": "2026-12-31T23:59:59Z",
  "due_complete": false,
  "badges": {},
  "cover": {},
  "desc_data": {}
}

Response: Created card object

Get Single Card

GET /api/cards/<card_id>

Get a card with full details including labels, checklists, and comments.

Response: Card object with nested labels, checklists, items, and comments

Update Card

PUT /api/cards/<card_id>

Update a card. Can also move card to different list by providing list_id.

Request Body: Partial card object

Response: Updated card object

Delete Card

DELETE /api/cards/<card_id>

Delete a card and all its associated data.

Response: Success message

Labels

Get Board Labels

GET /api/boards/<board_id>/labels

Get all labels for a board.

Response: Array of label objects

Create Label

POST /api/boards/<board_id>/labels

Create a new label in a board.

Request Body:

{
  "name": "Urgent",
  "color": "red"
}

Response: Created label object

Add Label to Card

POST /api/cards/<card_id>/labels

Add a label to a card.

Request Body:

{
  "label_id": 1
}

Response: Created card-label association object

Remove Label from Card

DELETE /api/cards/<card_id>/labels/<label_id>

Remove a label from a card.

Response: Success message

Checklists

Create Checklist

POST /api/cards/<card_id>/checklists

Create a new checklist in a card.

Request Body:

{
  "name": "Tasks",
  "pos": 0
}

Response: Created checklist object

Create Check Item

POST /api/checklists/<checklist_id>/items

Create a new check item in a checklist.

Request Body:

{
  "name": "Complete task",
  "pos": 0,
  "state": "incomplete",
  "due": "2026-12-31T23:59:59Z"
}

Response: Created check item object

Update Check Item

PUT /api/check-items/<item_id>

Update a check item (typically used to toggle state).

Request Body: Partial check item object

Response: Updated check item object

Delete Checklist

DELETE /api/checklists/<checklist_id>

Delete a checklist and all its items.

Response: Success message

Delete Check Item

DELETE /api/check-items/<item_id>

Delete a check item.

Response: Success message

Comments

Get Card Comments

GET /api/cards/<card_id>/comments

Get all comments for a card, ordered by creation date (newest first).

Response: Array of comment objects with user information

Create Comment

POST /api/cards/<card_id>/comments

Create a new comment on a card.

Request Body:

{
  "text": "This is a comment"
}

Response: Created comment object

Update Comment

PUT /api/comments/<comment_id>

Update a comment (only by the comment author).

Request Body: Partial comment object

Response: Updated comment object

Delete Comment

DELETE /api/comments/<comment_id>

Delete a comment (only by the comment author).

Response: Success message

Data Models

Board

{
  "id": 1,
  "name": "My Board",
  "description": "Board description",
  "closed": false,
  "url": "https://example.com",
  "short_link": "abc123",
  "short_url": "https://example.com/b/abc123",
  "user_id": 1,
  "date_last_activity": "2026-01-01T00:00:00Z",
  "date_last_view": "2026-01-01T00:00:00Z",
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z",
  "prefs": {},
  "label_names": {},
  "limits": {}
}

List

{
  "id": 1,
  "name": "To Do",
  "closed": false,
  "pos": 0,
  "board_id": 1,
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

Card

{
  "id": 1,
  "name": "Task Name",
  "description": "Task description",
  "closed": false,
  "due": "2026-12-31T23:59:59Z",
  "due_complete": false,
  "pos": 0,
  "id_short": 1,
  "board_id": 1,
  "list_id": 1,
  "date_last_activity": "2026-01-01T00:00:00Z",
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z",
  "badges": {},
  "cover": {},
  "desc_data": {},
  "labels": [],
  "checklists": [],
  "comments": []
}

Label

{
  "id": 1,
  "name": "Urgent",
  "color": "red",
  "uses": 0,
  "board_id": 1,
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

Checklist

{
  "id": 1,
  "name": "Tasks",
  "pos": 0,
  "board_id": 1,
  "card_id": 1,
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z",
  "items": []
}

Check Item

{
  "id": 1,
  "name": "Complete task",
  "pos": 0,
  "state": "incomplete",
  "due": "2026-12-31T23:59:59Z",
  "checklist_id": 1,
  "user_id": 1,
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

Comment

{
  "id": 1,
  "text": "Comment text",
  "card_id": 1,
  "user_id": 1,
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z",
  "user": {}
}

Common Response Codes

  • 200 OK - Request successful
  • 201 Created - Resource created successfully
  • 400 Bad Request - Invalid request data
  • 401 Unauthorized - Authentication required or invalid
  • 403 Forbidden - Access denied (not your resource)
  • 404 Not Found - Resource not found
  • 500 Internal Server Error - Server error

Usage Examples

Creating a complete board with lists and cards

# 1. Login to get token
curl -X POST http://localhost:5000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "password"}'

# 2. Create a board
curl -X POST http://localhost:5000/api/boards \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"name": "My Project"}'

# 3. Create a list
curl -X POST http://localhost:5000/api/boards/1/lists \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"name": "To Do", "pos": 0}'

# 4. Create a card
curl -X POST http://localhost:5000/api/lists/1/cards \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"name": "Task 1", "pos": 0}'

Adding labels to a card

# 1. Create a label
curl -X POST http://localhost:5000/api/boards/1/labels \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"name": "Urgent", "color": "red"}'

# 2. Add label to card
curl -X POST http://localhost:5000/api/cards/1/labels \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"label_id": 1}'

Creating a checklist with items

# 1. Create checklist
curl -X POST http://localhost:5000/api/cards/1/checklists \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"name": "Subtasks", "pos": 0}'

# 2. Add check items
curl -X POST http://localhost:5000/api/checklists/1/items \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"name": "Task 1", "pos": 0}'

# 3. Mark item as complete
curl -X PUT http://localhost:5000/api/check-items/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"state": "complete"}'

Adding comments

curl -X POST http://localhost:5000/api/cards/1/comments \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"text": "This is a comment"}'