# Flux API
> Kanban board management platform. Build automations, manage cards, and organize work.

## Authentication
All requests require a Bearer token (API key with `flux_` prefix).
Header: `Authorization: Bearer flux_YOUR_KEY`

## Base URL
Use the URL where you received this file (e.g. https://flux.umin.ai).

---

## Endpoints

### Workspaces
- GET /api/workspaces — List your workspaces. Returns: { workspaces: [{ id, name, slug }] }
- POST /api/workspaces — Create workspace. Body: { name }
- POST /api/workspaces/switch — Switch active workspace. Body: { workspaceId }

### Boards
- GET /api/boards — List boards in active workspace. Returns: { boards: [{ id, shortId, title, columns }] }
- GET /api/boards/all — List all boards across all workspaces.
- POST /api/boards — Create board. Body: { title, workspaceId? }
- GET /api/boards/{boardId} — Get board with columns and cards. Accepts shortId or UUID. Returns: { board: { id, title, columns }, cards: { [cardId]: card }, boardLabels, members }
- PATCH /api/boards/{boardId} — Update board. Body: { title?, settings?, doneColumnId? }
- DELETE /api/boards/{boardId} — Soft-delete board.

### Columns
- POST /api/columns — Create column. Body: { boardId, title }
- PATCH /api/columns — Update column. Body: { columnId, title?, isDone? }
- DELETE /api/columns?columnId={id} — Delete column.
- PUT /api/columns/reorder — Reorder columns. Body: { boardId, columnIds: [ordered UUIDs] }

### Cards
- POST /api/cards — Create card. Body: { boardId, columnId, title, description? }
- PATCH /api/cards — Update card. Body: { cardId, title?, description?, columnId?, assigneeIds?, dueDate?, coverUrl?, archivedAt? }
- DELETE /api/cards?cardId={id} — Soft-delete card.
- GET /api/cards/{cardId} — Full card detail (checklist, comments, attachments, labels, assignees).
- PUT /api/cards/reorder — Move/reorder cards. Body: { boardId, moves: [{ cardId, columnId, position }] }

### Card Sub-Resources
- POST /api/cards/{cardId}/checklist — Add checklist item. Body: { text }
- PATCH /api/cards/{cardId}/checklist — Update item. Body: { itemId, text?, done?, position? }
- DELETE /api/cards/{cardId}/checklist?itemId={id} — Delete item.

- POST /api/cards/{cardId}/comments — Add comment. Body: { content, parentId? }
- PATCH /api/cards/{cardId}/comments — Edit comment. Body: { commentId, content }
- DELETE /api/cards/{cardId}/comments?commentId={id} — Delete comment.

- POST /api/cards/{cardId}/labels — Toggle label on card. Body: { labelId }
- DELETE /api/cards/{cardId}/labels?labelId={id} — Remove label.

- POST /api/cards/{cardId}/attachments/upload-url — Get presigned S3 upload URL. Body: { fileName, mimeType }
- POST /api/cards/{cardId}/attachments — Register attachment after upload. Body: { fileName, fileUrl, s3Key?, mimeType? }
- DELETE /api/cards/{cardId}/attachments?attachmentId={id} — Delete attachment.

### Labels (Board-Level Definitions)
- POST /api/boards/{boardId}/labels — Create label. Body: { text, color }
- PATCH /api/boards/{boardId}/labels — Update label. Body: { labelId, text?, color? }
- DELETE /api/boards/{boardId}/labels?labelId={id} — Delete label.

### Search
- GET /api/search?q={query}&workspaceId={id?}&type={card|board?} — Full-text search.

### Undo
- POST /api/undo — Undo last action. Body: { boardId }

---

## Common Workflows

### Create a card on a board
1. GET /api/boards — find the board by title
2. GET /api/boards/{shortId} — get columns
3. POST /api/cards — create card in the target column

### Move a card to another column
1. GET /api/boards/{shortId} — find source/target column IDs and card position
2. PUT /api/cards/reorder — move with { boardId, moves: [{ cardId, columnId, position: 0 }] }

### Assign a member to a card
1. GET /api/boards/{shortId} — response includes `members` array with user IDs
2. PATCH /api/cards — send { cardId, assigneeIds: [userId1, userId2] }

### Add a label to a card
1. GET /api/boards/{shortId} — response includes `boardLabels` with label IDs
2. POST /api/cards/{cardId}/labels — send { labelId }

---

## Notes
- All write requests should include header: `X-Idempotency-Key: <uuid>` to prevent duplicates on retry.
- Card IDs have two formats: UUID (internal) and humanId (e.g. "TB-1", used in URLs).
- Board IDs accept both UUID and shortId (e.g. "av-tX6qQ").
- All deletes are soft-deletes (reversible via undo).
- Dates use ISO 8601 format.