kanban-app/docs/kanban_api.md

# 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:**
```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/<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:**
```json
{
  "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:**
```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/<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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```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/<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:**
```json
{
  "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
```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 <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

```bash
# 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

```bash
# 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

```bash
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"}'