# 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 ``` ## 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/ ``` 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:** ```json { "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/ ``` Update a board. **Request Body:** Partial board object (only include fields to update) **Response:** Updated board object ### Delete Board ``` DELETE /api/boards/ ``` Delete a board and all its associated data. **Response:** Success message ## Lists ### Create List ``` POST /api/boards//lists ``` Create a new list in a board. **Request Body:** ```json { "name": "To Do", "pos": 0 } ``` **Response:** Created list object ### Update List ``` PUT /api/lists/ ``` Update a list. **Request Body:** Partial list object **Response:** Updated list object ### Delete List ``` DELETE /api/lists/ ``` Delete a list and all its cards. **Response:** Success message ## Cards ### Create Card ``` POST /api/lists//cards ``` Create a new card in a list. **Request Body:** ```json { "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/ ``` 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/ ``` 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/ ``` Delete a card and all its associated data. **Response:** Success message ## Labels ### Get Board Labels ``` GET /api/boards//labels ``` Get all labels for a board. **Response:** Array of label objects ### Create Label ``` POST /api/boards//labels ``` Create a new label in a board. **Request Body:** ```json { "name": "Urgent", "color": "red" } ``` **Response:** Created label object ### Add Label to Card ``` POST /api/cards//labels ``` Add a label to a card. **Request Body:** ```json { "label_id": 1 } ``` **Response:** Created card-label association object ### Remove Label from Card ``` DELETE /api/cards//labels/ ``` Remove a label from a card. **Response:** Success message ## Checklists ### Create Checklist ``` POST /api/cards//checklists ``` Create a new checklist in a card. **Request Body:** ```json { "name": "Tasks", "pos": 0 } ``` **Response:** Created checklist object ### Create Check Item ``` POST /api/checklists//items ``` Create a new check item in a checklist. **Request Body:** ```json { "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/ ``` 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/ ``` Delete a checklist and all its items. **Response:** Success message ### Delete Check Item ``` DELETE /api/check-items/ ``` Delete a check item. **Response:** Success message ## Comments ### Get Card Comments ``` GET /api/cards//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//comments ``` Create a new comment on a card. **Request Body:** ```json { "text": "This is a comment" } ``` **Response:** Created comment object ### Update Comment ``` PUT /api/comments/ ``` Update a comment (only by the comment author). **Request Body:** Partial comment object **Response:** Updated comment object ### Delete Comment ``` DELETE /api/comments/ ``` Delete a comment (only by the comment author). **Response:** Success message ## Data Models ### Board ```json { "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 ```json { "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 ```json { "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 ```json { "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 ```json { "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 ```json { "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 ```json { "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 ```bash # 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 " \ -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 " \ -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 " \ -d '{"name": "Task 1", "pos": 0}' ``` ### Adding labels to a card ```bash # 1. Create a label curl -X POST http://localhost:5000/api/boards/1/labels \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -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 " \ -d '{"label_id": 1}' ``` ### Creating a checklist with items ```bash # 1. Create checklist curl -X POST http://localhost:5000/api/cards/1/checklists \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -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 " \ -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 " \ -d '{"state": "complete"}' ``` ### Adding comments ```bash curl -X POST http://localhost:5000/api/cards/1/comments \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -d '{"text": "This is a comment"}'