Tasks & boards

The Tasks API creates, lists, and moves tasks, and organizes them on boards. Use it to feed a personal task list from an external system, automate recurring work items, or sync a board's columns with another tool. Every task has a single owner — automation acts as that owner, and items it can't see are reported as not found rather than forbidden, so a caller can't discover another user's task IDs by probing.

Concepts

List your tasks

Lists are cursor-paginated and default to excluding archived tasks.

curl -sf "https://api.falcata.io/api/v1/kvark/tasks?status=todo&tags=ops,p1&limit=50" \
  -H "Authorization: Bearer $FURNACE_TOKEN" | jq '.data, .meta.nextCursor'

Pass archived=true to include archived tasks. Tags in the tags filter are AND-matched. Follow meta.nextCursor to get the next page; lists never return an exact total, only meta.hasMore.

Create and update a task

Creation accepts an idempotency key, so retrying a failed request with the same key returns the original task instead of creating a duplicate.

curl -sf -X POST "https://api.falcata.io/api/v1/kvark/tasks" \
  -H "Authorization: Bearer $FURNACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Investigate deploy","body":"Check runner logs","tags":["ops"],"idempotencyKey":"deploy-42"}'

Update fields with PATCH:

curl -sf -X PATCH "https://api.falcata.io/api/v1/kvark/tasks/$TASK_ID" \
  -H "Authorization: Bearer $FURNACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"dueAt":1780000000000}'

Pass an empty tags array to clear all tags, and clearDueAt/clearReminder to explicitly clear those fields (omitting them leaves the existing value alone).

Move and complete a task

Moving a task sets its status and, optionally, its board and position within the destination column.

curl -sf -X PATCH "https://api.falcata.io/api/v1/kvark/tasks/$TASK_ID/move" \
  -H "Authorization: Bearer $FURNACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"in_progress"}'

Use beforeTaskId or afterTaskId to control ordering within the destination column. Completing a task is a separate call:

curl -sf -X POST "https://api.falcata.io/api/v1/kvark/tasks/$TASK_ID/complete" \
  -H "Authorization: Bearer $FURNACE_TOKEN"

A recurring task advances its due date and returns to the board's entry column; a non-recurring task moves to the terminal column.

Archive, restore, and delete

Archiving hides a task from default listings without discarding it; deleting is permanent.

curl -sf -X POST "https://api.falcata.io/api/v1/kvark/tasks/$TASK_ID/archive" \
  -H "Authorization: Bearer $FURNACE_TOKEN"

curl -sf -X DELETE "https://api.falcata.io/api/v1/kvark/tasks/$TASK_ID" \
  -H "Authorization: Bearer $FURNACE_TOKEN"

Work with boards

Boards group tasks into columns you move them through.

curl -sf "https://api.falcata.io/api/v1/kvark/boards" \
  -H "Authorization: Bearer $FURNACE_TOKEN" | jq '.data'

curl -sf -X POST "https://api.falcata.io/api/v1/kvark/boards" \
  -H "Authorization: Bearer $FURNACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Launch checklist","description":"Q3 site launch"}'

Inspect a board's structure with GET /kvark/boards/{id}/columns and GET /kvark/boards/{id}/placements.

Activate task listing

Task and tag reads run against a per-caller index. Before your first automated list against a new token, run the backfill once:

curl -sf -X POST "https://api.falcata.io/api/v1/kvark/task-index/backfill" \
  -H "Authorization: Bearer $FURNACE_TOKEN"

The command is resumable and safe to run repeatedly — it processes a bounded batch per call and picks up where it left off. Until activation completes, list and tag reads fail with a recovery error naming this command rather than falling back to a slow scan.

/api/v1/tasks is a compatibility alias for the same caller-owned tasks and also works in every example above.

Everything else — attachment subresources on legacy items, board sharing, and full field-by-field schemas — is in the full reference.