Tasks

List task lists

GET/task_lists

Task lists, in the owner's order.

curl "$NIFTY_URL/api/v1/task_lists" \
  -H "Authorization: Bearer $NIFTY_TOKEN"

Query parameters

Response

200 OK Errors: 400 401 429

{
  "data": [
    {
      "id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
      "name": "Garden",
      "color": "emerald",
      "icon": "leaf",
      "position": 1,
      "created_at": "2026-10-10T09:30:00Z",
      "updated_at": "2026-10-10T09:30:00Z"
    }
  ],
  "meta": {
    "next_cursor": "eyJrIjpbIjIwMjYtMTAtMDlUMDg6MzA6MDBaIl19",
    "limit": 1,
    "total_count": 1
  }
}

Add a task list

POST/task_lists

Needs a name. Goes last unless position is sent. A blank color gets the first one no other list uses (colours and icons are those of GET /category_choices).

curl -X POST "$NIFTY_URL/api/v1/task_lists" \
  -H "Authorization: Bearer $NIFTY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"task_list":{"name":"Garden","color":"emerald","icon":"leaf"}}'

Headers

Request body

Response

201 Created Errors: 400 401 403 409 415 422 429

{
  "data": {
    "id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
    "name": "Garden",
    "color": "emerald",
    "icon": "leaf",
    "position": 1,
    "created_at": "2026-10-10T09:30:00Z",
    "updated_at": "2026-10-10T09:30:00Z"
  }
}

Get a task list

GET/task_lists/{id}

curl "$NIFTY_URL/api/v1/task_lists/01j9zq3k8m5x2v7c4n6b0t1r9e" \
  -H "Authorization: Bearer $NIFTY_TOKEN"

Path parameters

Response

200 OK Errors: 401 404 429

{
  "data": {
    "id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
    "name": "Garden",
    "color": "emerald",
    "icon": "leaf",
    "position": 1,
    "created_at": "2026-10-10T09:30:00Z",
    "updated_at": "2026-10-10T09:30:00Z"
  }
}

Change or move a task list

PATCH/task_lists/{id}

Also PUT /task_lists/{id}, the same.

Only the fields sent change. Sending position moves the list there and renumbers the live lists 1..n; the others whose position changed get a new updated_at, so re-sync with updated_since after a move. Tasks hold only task_list_id, so renaming or recolouring a list changes no task.

curl -X PATCH "$NIFTY_URL/api/v1/task_lists/01j9zq3k8m5x2v7c4n6b0t1r9e" \
  -H "Authorization: Bearer $NIFTY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"task_list":{"name":"Garden","color":"emerald","icon":"leaf"}}'

Path parameters

Request body

Response

200 OK Errors: 400 401 403 404 415 422 429

{
  "data": {
    "id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
    "name": "Garden",
    "color": "emerald",
    "icon": "leaf",
    "position": 1,
    "created_at": "2026-10-10T09:30:00Z",
    "updated_at": "2026-10-10T09:30:00Z"
  }
}

Delete a task list

DELETE/task_lists/{id}

Delete a task list and its tasks.

Restorable for 20 seconds (POST /task_lists/{id}/restoration), then permanent. The list and its tasks are gone from every endpoint at once, with deletion records for the list and each of its tasks. Its name is free for a new list at once. Deleting again is a 404.

curl -X DELETE "$NIFTY_URL/api/v1/task_lists/01j9zq3k8m5x2v7c4n6b0t1r9e" \
  -H "Authorization: Bearer $NIFTY_TOKEN"

Path parameters

Response

204 Deleted Errors: 401 403 404 429

Restore a task list

POST/task_lists/{task_list_id}/restoration

Undo deleting a task list.

Within 20 seconds of DELETE /task_lists/{id}: brings the list back with its tasks. Their deletion records are removed, and they get a new updated_at. A task deleted on its own before the list stays deleted. If another list took its name meanwhile, it comes back renamed "Name (2)", so check name. No body. Restoring a list that isn't deleted changes nothing and returns it, so a retry is safe. Once the 20 seconds have passed, or for an unknown id, it's a 404. If other lists take the name it picks twice in a row, it's a 422 on name; try again.

curl -X POST "$NIFTY_URL/api/v1/task_lists/01j9zq3k8m5x2v7c4n6b0t1r9e/restoration" \
  -H "Authorization: Bearer $NIFTY_TOKEN"

Path parameters

Headers

Response

200 Restored. The list, as GET /task_lists/{id} returns it. Errors: 400 401 403 404 409 415 422 429

{
  "data": {
    "id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
    "name": "Garden",
    "color": "emerald",
    "icon": "leaf",
    "position": 1,
    "created_at": "2026-10-10T09:30:00Z",
    "updated_at": "2026-10-10T09:30:00Z"
  }
}

List tasks

GET/tasks

Live tasks: not deleted, and not in a deleted list, person or project. Filters combine (AND); they're for browsing, so sync unfiltered. Without view or status, every status is listed. Before answering, open tasks whose expires_on has passed are archived (as every task endpoint does), so none is listed as open.

curl "$NIFTY_URL/api/v1/tasks" \
  -H "Authorization: Bearer $NIFTY_TOKEN"

Query parameters

Response

200 OK Errors: 400 401 429

{
  "data": [
    {
      "id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
      "title": "Book the plumber",
      "status": "open",
      "start_on": "2026-10-10",
      "deadline_on": "2026-10-10",
      "expires_on": "2026-10-10",
      "completed_at": "2026-10-10T09:30:00Z",
      "archived_at": "2026-10-10T09:30:00Z",
      "task_list_id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
      "person_id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
      "project_id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
      "position": 1,
      "description_html": "<p>Ask about the boiler too.</p>",
      "description_text": "Ask about the boiler too.",
      "has_documents": true,
      "expired": true,
      "created_at": "2026-10-10T09:30:00Z",
      "updated_at": "2026-10-10T09:30:00Z"
    }
  ],
  "meta": {
    "next_cursor": "eyJrIjpbIjIwMjYtMTAtMDlUMDg6MzA6MDBaIl19",
    "limit": 1,
    "total_count": 1
  }
}

Add a task

POST/tasks

Needs a title. A new task is open unless status is sent, in the Inbox unless a home id is sent, and goes to the top of its home's open tasks unless position is sent (a closed one, to the bottom). Going to the top changes no other task: its position is one less than the first's, so it may be zero or negative.

curl -X POST "$NIFTY_URL/api/v1/tasks" \
  -H "Authorization: Bearer $NIFTY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"task":{"title":"Book the plumber","deadline_on":"2026-10-16","project_id":"01j9zq3p4q6r8s0t2v5w7x9y1z"}}'

Headers

Request body

Response

201 Created Errors: 400 401 403 409 415 422 429

{
  "data": {
    "id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
    "title": "Book the plumber",
    "status": "open",
    "start_on": "2026-10-10",
    "deadline_on": "2026-10-10",
    "expires_on": "2026-10-10",
    "completed_at": "2026-10-10T09:30:00Z",
    "archived_at": "2026-10-10T09:30:00Z",
    "task_list_id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
    "person_id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
    "project_id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
    "position": 1,
    "description_html": "<p>Ask about the boiler too.</p>",
    "description_text": "Ask about the boiler too.",
    "has_documents": true,
    "expired": true,
    "created_at": "2026-10-10T09:30:00Z",
    "updated_at": "2026-10-10T09:30:00Z"
  }
}

Get a task

GET/tasks/{id}

A deleted task, or one in a deleted list, person or project, is a 404.

curl "$NIFTY_URL/api/v1/tasks/01j9zq3k8m5x2v7c4n6b0t1r9e" \
  -H "Authorization: Bearer $NIFTY_TOKEN"

Path parameters

Response

200 OK Errors: 401 404 429

{
  "data": {
    "id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
    "title": "Book the plumber",
    "status": "open",
    "start_on": "2026-10-10",
    "deadline_on": "2026-10-10",
    "expires_on": "2026-10-10",
    "completed_at": "2026-10-10T09:30:00Z",
    "archived_at": "2026-10-10T09:30:00Z",
    "task_list_id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
    "person_id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
    "project_id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
    "position": 1,
    "description_html": "<p>Ask about the boiler too.</p>",
    "description_text": "Ask about the boiler too.",
    "has_documents": true,
    "expired": true,
    "created_at": "2026-10-10T09:30:00Z",
    "updated_at": "2026-10-10T09:30:00Z"
  }
}

Change a task

PATCH/tasks/{id}

Also PUT /tasks/{id}, the same.

Change, move, complete or reopen a task.

Only the fields sent change. Moving it to another home puts it at the bottom there unless position is sent too. Sending position moves it among its home's open tasks and renumbers them 1..n; the others whose position changed get a new updated_at, so re-sync with updated_since after a move.

curl -X PATCH "$NIFTY_URL/api/v1/tasks/01j9zq3k8m5x2v7c4n6b0t1r9e" \
  -H "Authorization: Bearer $NIFTY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"task":{"title":"Book the plumber","deadline_on":"2026-10-16","project_id":"01j9zq3p4q6r8s0t2v5w7x9y1z"}}'

Path parameters

Request body

Response

200 OK Errors: 400 401 403 404 415 422 429

{
  "data": {
    "id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
    "title": "Book the plumber",
    "status": "open",
    "start_on": "2026-10-10",
    "deadline_on": "2026-10-10",
    "expires_on": "2026-10-10",
    "completed_at": "2026-10-10T09:30:00Z",
    "archived_at": "2026-10-10T09:30:00Z",
    "task_list_id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
    "person_id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
    "project_id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
    "position": 1,
    "description_html": "<p>Ask about the boiler too.</p>",
    "description_text": "Ask about the boiler too.",
    "has_documents": true,
    "expired": true,
    "created_at": "2026-10-10T09:30:00Z",
    "updated_at": "2026-10-10T09:30:00Z"
  }
}

Delete a task

DELETE/tasks/{id}

Restorable for 20 seconds (POST /tasks/{id}/restoration), then permanent. Writes a task deletion record at once. Deleting again is a 404.

curl -X DELETE "$NIFTY_URL/api/v1/tasks/01j9zq3k8m5x2v7c4n6b0t1r9e" \
  -H "Authorization: Bearer $NIFTY_TOKEN"

Path parameters

Response

204 Deleted Errors: 401 403 404 429

Restore a task

POST/tasks/{task_id}/restoration

Undo deleting a task.

Within 20 seconds of DELETE /tasks/{id}: brings the task back, removes its deletion record and gives it a new updated_at. No body. Restoring a task that isn't deleted changes nothing and returns it, so a retry is safe. Once the 20 seconds have passed, for an unknown id, or while its list, person or project is deleted (restore that instead), it's a 404. If its expiry passed meanwhile, it comes back archived.

curl -X POST "$NIFTY_URL/api/v1/tasks/01j9zq3k8m5x2v7c4n6b0t1r9e/restoration" \
  -H "Authorization: Bearer $NIFTY_TOKEN"

Path parameters

Headers

Response

200 Restored. The task, as GET /tasks/{id} returns it. Errors: 400 401 403 404 409 415 429

{
  "data": {
    "id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
    "title": "Book the plumber",
    "status": "open",
    "start_on": "2026-10-10",
    "deadline_on": "2026-10-10",
    "expires_on": "2026-10-10",
    "completed_at": "2026-10-10T09:30:00Z",
    "archived_at": "2026-10-10T09:30:00Z",
    "task_list_id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
    "person_id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
    "project_id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
    "position": 1,
    "description_html": "<p>Ask about the boiler too.</p>",
    "description_text": "Ask about the boiler too.",
    "has_documents": true,
    "expired": true,
    "created_at": "2026-10-10T09:30:00Z",
    "updated_at": "2026-10-10T09:30:00Z"
  }
}

Task counts per list

GET/task_counts

How many open tasks are in the Inbox, Today, due soon, overdue and each list; and one page's counts.

Live, open tasks, with today in the owner's time zone; each count except overdue matches its GET /tasks listing. Expired tasks are archived first. Not a record: there's nothing to sync, so ask again when tasks change.

Name a page with view, or one home (inbox, task_list_id, person_id or project_id), to get its counts in page. view=logbook may also name one home. An unknown or hidden home counts zeros.

curl "$NIFTY_URL/api/v1/task_counts" \
  -H "Authorization: Bearer $NIFTY_TOKEN"

Query parameters

Response

200 OK Errors: 400 401 429

{
  "data": {
    "inbox": 1,
    "today": 1,
    "due_soon": 1,
    "overdue": 1,
    "task_lists": [
      {
        "id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
        "open": 1
      }
    ],
    "page": {
      "open": 1,
      "completed": 1,
      "completed_today": 1,
      "overdue": 1,
      "wont_do": 1,
      "expired": 1
    }
  }
}

Task counts per project

GET/project_task_counts

Each project's open and completed tasks, and its next task.

Live tasks of live projects, by project_id; a project with none is left out (archived tasks aren't counted). next_task is the open task to do next: started ones (no start_on, or today or earlier in the owner's time zone) first, then by deadline_on (none last), position and id; null when none is open. Expired tasks are archived first. Not paginated, and not a record: ask again when tasks change.

curl "$NIFTY_URL/api/v1/project_task_counts" \
  -H "Authorization: Bearer $NIFTY_TOKEN"

Response

200 OK Errors: 401 429

{
  "data": [
    {
      "project_id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
      "open": 1,
      "completed": 1,
      "next_task": {
        "id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
        "title": "string",
        "start_on": "2026-10-10",
        "deadline_on": "2026-10-10"
      }
    }
  ]
}