Flux

Flux is a kanban board management platform. Use this skill to build automations, manage cards, and organize work through the Flux REST API.

Setup

• FLUX_API_KEY (required) — an API key beginning with flux_. Every request is authenticated with it.
• FLUX_BASE_URL (optional) — the origin of the Flux instance, e.g. https://flux.umin.ai. Defaults to https://flux.umin.ai.

Authentication

Send the key as a Bearer token on every request:

Authorization: Bearer flux_YOUR_KEY

API keys carry granular scopes, so a request may succeed for reads but be rejected for writes if the key lacks the scope. A 401 means the key is missing or invalid; a 403 means the key is valid but not permitted for that action.

Core concepts

• Active workspace — most board/card endpoints operate on the active workspace tied to the key. List workspaces with GET /api/workspaces, change it with POST /api/workspaces/switch.
• Two ID formats — boards accept either a UUID or a short URL id (shortId, e.g. av-tX6qQ). Cards have an internal UUID and a human id (humanId, e.g. TB-1) used in URLs. Use the UUID for write operations unless an endpoint says otherwise.
• Cache key gotcha — a board is keyed by its shortId, not by card.boardId (which is a UUID). Don't assume the two are interchangeable when matching a card to its board.
• Soft deletes — every DELETE is reversible. Deleted records are hidden, not destroyed, and can be restored via POST /api/undo.
• Idempotency — include X-Idempotency-Key: \x3Cuuid> on every write (POST/PATCH/PUT/ DELETE). On retry, Flux returns the original result instead of duplicating the action.
• Dates — all timestamps are ISO 8601.

Endpoints

Workspaces

Boards

Columns

Cards

Card sub-resources

Checklist

Comments

Labels on a card (toggle a board-level label onto the card)

Attachments

Labels (board-level definitions)

Search & undo

Common workflows

Create a card on a board

1. GET /api/boards — find the board by title, note its shortId.
2. GET /api/boards/{shortId} — read board.columns to pick the target columnId.
3. POST /api/cards with { boardId, columnId, title }.

Move a card to another column

1. GET /api/boards/{shortId} — find the source/target columnIds and the card.
2. PUT /api/cards/reorder with { boardId, moves: [{ cardId, columnId, position: 0 }] } (position: 0 drops it at the top of the target column).

Assign members to a card

1. GET /api/boards/{shortId} — the response members array lists user IDs.
2. PATCH /api/cards with { cardId, assignees: [userId1, userId2] }. Assignees are replaced wholesale — send the full desired list, not a delta. Note: the write field is assignees; board reads expose the same data as assigneeIds. Sending assigneeIds to PATCH is silently ignored and returns 422 "No updates provided".

Add a label to a card

1. GET /api/boards/{shortId} — the response boardLabels array lists label IDs. (Create the label first with POST /api/boards/{boardId}/labels if it doesn't exist.)
2. POST /api/cards/{cardId}/labels with { labelId }.

Notes & gotchas

• Always send X-Idempotency-Key: \x3Cuuid> on writes to make retries safe.
• All deletes are soft and reversible via POST /api/undo.
• Board IDs accept both UUID and shortId; card IDs have a UUID and a humanId (TB-1).
• Resolve a board's columns and labels before creating or moving cards — you need their IDs from GET /api/boards/{shortId}.
• A 403 on a write usually means the API key lacks the required scope, not that the resource is missing.