Kanban and tasks, by behavior

Works today at: POST /api/v1/kanban/boards/{boardId}/query

Free query within a board

The raw query gate, scoped to one board. You send a complete query string and the server only applies the board's visibility scope. Free querying is a product feature and stays; the semantic column read above absorbs only the most common shape.

Request body

Request

POST /api/v1/boards/7d55a212-30f5-4a41-a5da-b2f7f01f3bb9/query HTTP/1.1
Host: api.oatnil.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "query": "(status = 'doing') ORDER BY metadata.order ASC",
  "page": 1,
  "page_size": 20
}

curl -s "$UD_API/api/v1/boards/7d55a212-30f5-4a41-a5da-b2f7f01f3bb9/query" \
  -H "Authorization: Bearer $UD_TOKEN" -H "Content-Type: application/json" \
  -d "{\"query\":\"(status = 'doing') ORDER BY metadata.order ASC\",\"page\":1,\"page_size\":20}"

Response

{
  "data": [
    {
      "id": "7c2f6a1e-4b09-4d2a-9e51-2f8c3d7b9a10",
      "title": "Retry payment callback on timeout",
      "description": "",
      "status": "doing",
      "path": "",
      "tags": ["dev", "urgent"],
      "checkInCount": 0,
      "metadata": {"ud.sprint": "3f6d9a52-88a1-4f0e-b1d4-6c1f2e7a9b31", "order": 3},
      "created_at": "2026-09-22T08:01:44Z",
      "created_by": "9a7e5c21-1b3f-4e8a-92d6-04c8f1a7d502",
      "updated_at": "2026-09-25T10:12:03Z",
      "updated_by": "9a7e5c21-1b3f-4e8a-92d6-04c8f1a7d502"
    }
  ],
  "total": 9,
  "page": 1
}

Works today at: POST /api/v1/kanban/boards/{boardId}/tasks

Create a card on a board

Creates a task associated with the board; the server merges the board default_tags in. Today the client decides the initial status/tags itself. The Draft column_id field changes that: name the column, and the server computes the initial values from the column's enter actions (your explicit fields always win).

Request body

Request

POST /api/v1/boards/7d55a212-30f5-4a41-a5da-b2f7f01f3bb9/tasks HTTP/1.1
Host: api.oatnil.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Export support tickets",
  "description": "CSV and XLSX",
  "status": "todo",
  "tags": ["dev"]
}

curl -s "$UD_API/api/v1/boards/7d55a212-30f5-4a41-a5da-b2f7f01f3bb9/tasks" \
  -H "Authorization: Bearer $UD_TOKEN" -H "Content-Type: application/json" \
  -d '{"title":"Export support tickets","description":"CSV and XLSX","status":"todo","tags":["dev"]}'

Response

{
  "id": "b7e02c4d-9a31-4f6e-8c25-d10f4a7b3e92",
  "title": "Export support tickets",
  "description": "CSV and XLSX",
  "status": "todo",
  "path": "",
  "tags": ["dev", "q4"],
  "checkInCount": 0,
  "created_at": "2026-09-26T09:14:03Z",
  "created_by": "9a7e5c21-1b3f-4e8a-92d6-04c8f1a7d502",
  "updated_at": "2026-09-26T09:14:03Z",
  "updated_by": "9a7e5c21-1b3f-4e8a-92d6-04c8f1a7d502"
}

In this sample "q4" arrived from the board default_tags — the one initial value the server already merges today.

Move a card to another column

Single-transaction move. The server computes merge(exit(from), enter(to)) and writes once — replacing today's client-side sequence of one update plus N metadata patches, which can fail halfway. dry_run: true computes without writing, for confirmation UIs.

Request body

Request

POST /api/v1/boards/7d55a212-30f5-4a41-a5da-b2f7f01f3bb9/tasks/7c2f6a1e-4b09-4d2a-9e51-2f8c3d7b9a10/move HTTP/1.1
Host: api.oatnil.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "from_column_id": "col-todo",
  "to_column_id": "col-doing",
  "dry_run": false
}

curl -s "$UD_API/api/v1/boards/7d55a212-30f5-4a41-a5da-b2f7f01f3bb9/tasks/7c2f6a1e-4b09-4d2a-9e51-2f8c3d7b9a10/move" \
  -H "Authorization: Bearer $UD_TOKEN" -H "Content-Type: application/json" \
  -d '{"from_column_id":"col-todo","to_column_id":"col-doing","dry_run":false}'

Response

{
  "task": {
    "id": "7c2f6a1e-4b09-4d2a-9e51-2f8c3d7b9a10",
    "title": "Retry payment callback on timeout",
    "status": "doing",
    "tags": ["dev", "urgent"]
  },
  "applied_actions": [
    {"op": "set", "field": "status", "from": "todo", "to": "doing"},
    {"op": "add_tags", "value": ["dev"]}
  ]
}

{
  "code": "KANBAN_TASK_NOT_IN_SOURCE_COLUMN",
  "message": "task 7c2f6a1e-4b09-4d2a-9e51-2f8c3d7b9a10 no longer matches the query of column col-todo",
  "task": {
    "id": "7c2f6a1e-4b09-4d2a-9e51-2f8c3d7b9a10",
    "status": "doing",
    "tags": ["dev", "urgent"]
  }
}

Highlighted: what the server actually did — also exactly what dry_run returns for a confirmation dialog.

Errors

Works today at: PATCH /api/v1/todolist/{taskId}/metadata

Reorder in a column / assign to a sprint

Patches one metadata key per call. Reordering inside a column writes "order"; putting a card into a sprint writes "ud.sprint". Removing a key (taking a card out of a sprint) is the DELETE twin: DELETE /api/v1/tasks/{taskId}/metadata/{key}.

Request body

Request

PATCH /api/v1/tasks/7c2f6a1e-4b09-4d2a-9e51-2f8c3d7b9a10/metadata HTTP/1.1
Host: api.oatnil.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "key": "order",
  "value": 12
}

curl -s -X PATCH "$UD_API/api/v1/tasks/7c2f6a1e-4b09-4d2a-9e51-2f8c3d7b9a10/metadata" \
  -H "Authorization: Bearer $UD_TOKEN" -H "Content-Type: application/json" \
  -d '{"key":"order","value":12}'

Works today at: GET | POST | DELETE /api/v1/todolist/{taskId}

Open, edit, delete a card

The generic task detail family: GET reads (with notes and linked items), PATCH /api/v1/tasks/{taskId} updates, DELETE soft-deletes. The update is a partial update — every field is optional and an omitted field stays unchanged; for assignee, kickoff and deadline an explicit empty string means "clear". Note the verb change in the contract: today the update answers to POST at the old path; the target verb is PATCH, which is what the semantics have been all along.

Request

PATCH /api/v1/tasks/7c2f6a1e-4b09-4d2a-9e51-2f8c3d7b9a10 HTTP/1.1
Host: api.oatnil.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "status": "done",
  "deadline": ""
}

curl -s -X PATCH "$UD_API/api/v1/tasks/7c2f6a1e-4b09-4d2a-9e51-2f8c3d7b9a10" \
  -H "Authorization: Bearer $UD_TOKEN" -H "Content-Type: application/json" \
  -d '{"status":"done","deadline":""}'

Works today at: POST /api/v1/todolist/query

Backlog, sprint members, any free query

The global query gate: SQL-like syntax over built-in fields, tags, ud.* and cf.* metadata. Backlog views, sprint member lists and every ad-hoc slice go through here. Free querying is a product feature and stays — the semantic endpoints above only absorb the most common shape ("give me a column").

Request body

Request

POST /api/v1/tasks/query HTTP/1.1
Host: api.oatnil.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "query": "(status = 'todo') AND ('q4' IN tags) ORDER BY metadata.order ASC",
  "page": 1,
  "pageSize": 20,
  "view": "lite"
}

curl -s "$UD_API/api/v1/tasks/query" \
  -H "Authorization: Bearer $UD_TOKEN" -H "Content-Type: application/json" \
  -d "{\"query\":\"(status = 'todo') AND ('q4' IN tags) ORDER BY metadata.order ASC\",\"page\":1,\"pageSize\":20,\"view\":\"lite\"}"

Response

{
  "data": [
    {
      "id": "4de19b0c-2f6a-47d3-b8a1-9c05e2f7d614",
      "title": "Sign-up page A/B test",
      "status": "todo",
      "path": "",
      "tags": ["q4", "growth"],
      "checkInCount": 0,
      "metadata": {"order": 5},
      "created_at": "2026-09-18T02:11:09Z",
      "created_by": "9a7e5c21-1b3f-4e8a-92d6-04c8f1a7d502",
      "updated_at": "2026-09-24T11:40:52Z",
      "updated_by": "9a7e5c21-1b3f-4e8a-92d6-04c8f1a7d502"
    }
  ],
  "total": 14,
  "page": 1,
  "pageSize": 20,
  "totalPages": 1
}

In "lite" view the description field is absent (not empty) — an absent description means "fetch the task to get the body", never "this card has no body".

Works today at: POST /api/v1/todolist/{sprintId}/close-sprint

Close a sprint

The close ceremony in one server-side transaction: rolls unfinished members to the target, settles velocity, writes the retro note, marks the sprint done. Milestone-ordered — the sprint only flips to done after every rollover succeeded, so retries are safe.

Request body

Request

POST /api/v1/tasks/3f6d9a52-88a1-4f0e-b1d4-6c1f2e7a9b31/close-sprint HTTP/1.1
Host: api.oatnil.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "rollover": "backlog"
}

curl -s "$UD_API/api/v1/tasks/3f6d9a52-88a1-4f0e-b1d4-6c1f2e7a9b31/close-sprint" \
  -H "Authorization: Bearer $UD_TOKEN" -H "Content-Type: application/json" \
  -d '{"rollover":"backlog"}'

Response

{
  "sprintId": "3f6d9a52-88a1-4f0e-b1d4-6c1f2e7a9b31",
  "target": "backlog",
  "completed": 11,
  "rolledOver": 4,
  "rotatedBoardIds": ["7d55a212-30f5-4a41-a5da-b2f7f01f3bb9"],
  "skippedBoardIds": [],
  "velocity": 23.5
}

Highlighted: the boards whose active-sprint pointer this close moved (rotatedBoardIds) and the ones it left for a group admin (skippedBoardIds).

Errors