API reference

{ "groups": Group[] }

{ "group": Group }

{ "group": Group }

{ "group": Group }

{
  "lists": [
    {
      "id":        "6f8a6f4e-9b0e-4a82-9f6b-2a3f1e4a5d1a",
      "parent_id": null,
      "name":      "Work",
      "color":     "#0a84ff",
      "icon":      "briefcase",
      "archived":  false,
      "is_owner":  true,
      "is_shared": false
    }
  ]
}

Lists can be shared (the "Share" button on the site). The response contains both your own and shared ones; two boolean fields help tell them apart:

• is_owner - true: you own the list; false: you're a member of someone else's. Only the owner can edit the list itself (name, color, icon, archive, delete, attach to a group) - a member attempt returns 403. The contents (tasks and notes) can be edited by both.
• is_shared - true: the list has members (shared), regardless of your role; false: strictly personal.

In shared lists, the completed_user_id / deleted_user_id fields on tasks show who actually closed/deleted the record (not its owner).

{
  "list": {
    "id":        "6f8a6f4e-...",
    "parent_id": null,
    "name":      "Shopping",
    "color":     "#0a84ff",
    "icon":      null,
    "archived":  false
  }
}

{ "list": List }

{ "list": List }

{
  "parent_id": UUID | null   // null - move to root
}

{ "list": List }

{
  "list":   { "id": "...", "name": "Work" },
  "total":  42,
  "limit":  50,
  "offset": 0,
  "tasks":  [ Task, Task, ... ]
}

total is the number of tasks matching the filter before applying limit/offset.

Every task (as well as every note and notification) has a files array - attachments. If nothing is attached the array is empty.

"files": [
  {
    "id":     "9f1c...",
    "name":   "contract.pdf",
    "size":   184320,                                 // bytes
    "url":    "https://taskid.app/files/aa/bb/cc/9f1c....pdf",
    "source": "upload"                                // 'upload' | 'link'
  },
  {
    "id":     "1a2b...",
    "name":   "Status page",
    "size":   0,                                      // 0 if HEAD didn't return Content-Length
    "url":    "https://status.example.com/incidents/42",
    "source": "link"
  }
]

• source: "upload" - a file actually uploaded to our storage. url points to taskid.app and downloads via a plain GET without headers (capability token is baked into the path). Counts against the user's file quota.
• source: "link" - an external HTTPS URL (our server doesn't download or store anything). url points to the third-party resource as-is. Doesn't count against the quota; size may be 0 if the resource server didn't return Content-Length in the HEAD response on attach.
• Deleted/detached files and links are not returned in the array.
• Attach / detach - see "Attach files and links to a task" and "Detach a file/link from a task". The semantics for notes and notifications are identical.

{
  "task": {
    "id": "3c6b...-...-...",
    "list_id": "6f8a6f4e-...",
    "title": "Call the doctor",
    "note": null,
    "due_at": "2026-04-20T08:00:00Z",
    "due_has_time": true,
    "completed_at": null,
    "flagged": true,
    "priority": 2,
    "sort_order": 12000,
    "files": [],
    "version": "2026-04-18T12:34:56Z",
    "updated_at": "2026-04-18T12:34:56Z"
  }
}

{ "task": Task }

{ "task": Task }

The full task field structure is in the "Data types" section.

{ "task": Task }

{ "task": Task }

{
  "parent_id": UUID | null   // null - detach
}

• the parent must be in the same list as the task;
• the parent itself must not be a subtask (single-level hierarchy);
• the task :id must not have subtasks of its own;
• a task cannot be made a subtask of itself.

{ "task": Task }

The full updated task with the attached files and links already in the files array (see "Data types" - one unified format with a source marker):

{
  "task": {
    "id":     "TASK_ID",
    "title":  "Contractor agreement",
    "note":   null,
    "files": [
      {
        "id":     "9f1c-...",
        "name":   "contract.pdf",
        "size":   184320,
        "url":    "https://taskid.app/files/aa/bb/cc/9f1c....pdf",
        "source": "upload"
      },
      {
        "id":     "1a2b-...",
        "name":   "Dashboard",
        "size":   0,
        "url":    "https://grafana.example.com/d/api",
        "source": "link"
      }
    ],
    ...                            // remaining task fields - see "Data types"
  }
}

The full updated task - the file is no longer in the files array:

{
  "task": {
    "id":    "TASK_ID",
    "title": "Contractor agreement",
    "files": [],         // or an array with the remaining files
    ...
  }
}

If no such file is attached to the task (or it was already detached) - 404 is returned.

• limit - 1..500, default 100
• offset - which note to start from, default 0

{
  "list":    { "id": UUID, "name": string },
  "total":   number,
  "limit":   number,
  "offset":  number,
  "records": InfoRecord[]
}

Notes have the same files array as tasks: id, name, size, url (absolute, no Authorization required). Detached/deleted files are not returned. To attach/detach a file - see "Attach files to a note" and "Detach a file from a note".

{
  "record": {
    "id":         "INFO_ID",
    "list_id":    "LIST_ID",
    "title":      "Wi-Fi password",
    "note":       "Secret1234",
    "sort_order": 12000,
    "files":      [],
    "version":    "2026-04-18T12:34:56Z",
    "updated_at": "2026-04-18T12:34:56Z"
  }
}

{ "record": InfoRecord }

{ "record": InfoRecord }   // the full note after the changes

The field structure is in the "Data types" section.

{
  "file_ids": ["UUID", ...],            // optional
  "links":    [{ "url": "...", "name": "..." }, ...]  // optional
}

The full updated note - the attached files and links are already visible in the files array:

{
  "record": {
    "id":    "INFO_ID",
    "title": "Wi-Fi password",
    "note":  "Secret1234",
    "files": [
      {
        "id":     "9f1c-...",
        "name":   "router-photo.jpg",
        "size":   92210,
        "url":    "https://taskid.app/files/aa/bb/cc/9f1c....jpg",
        "source": "upload"
      },
      {
        "id":     "1a2b-...",
        "name":   "Wiki",
        "size":   0,
        "url":    "https://wiki.example.com/wifi",
        "source": "link"
      }
    ],
    ...
  }
}

The full updated note - this file is no longer in the files array:

{
  "record": {
    "id":    "INFO_ID",
    "title": "Wi-Fi password",
    "files": [],         // or the remaining files
    ...
  }
}

If no such file is attached to the note - 404 is returned.

{
  "notification": {
    "id":           "NOTIF_ID",
    "list_id":      null,
    "title":        "Prod is down",
    "note":         "503 on api.example.com",
    "priority":     3,
    "completed_at": null,
    "sort_order":   12000,
    "files": [
      {
        "id":     "1a2b-...",
        "name":   "Dashboard",
        "size":   0,
        "url":    "https://grafana.example.com/d/api",
        "source": "link"
      }
    ],
    "version":      "2026-04-18T12:34:56Z",
    "updated_at":   "2026-04-18T12:34:56Z",
    "date_create":  "2026-04-18T12:34:56Z"
  }
}

HTTP 201 on creation. If the request is repeated with the same Idempotency-Key - HTTP 200 with the same body (no new record is created).

Not to be confused with write_notifications - that one only allows creating notifications (POST /notifications). Attaching files needs full write.

{
  "file_ids": ["UUID", ...],            // optional
  "links":    [{ "url": "...", "name": "..." }, ...]  // optional
}

multipart/form-data. The form field is files (multiple values allowed) or file (a single one). Both are accepted.

{
  "files": [
    { "id": "9f1c-...", "name": "contract.pdf", "size": 184320 },
    { "id": "5b2e-...", "name": "photo.jpg",    "size":  92210 }
  ]
}

No download URL is returned at this step - you'll only need it once the file is attached to a task or note; there it comes back as an absolute URL inside the files array.

• 400 - body is not multipart or no files / empty file.
• 413 - maximum request or single-file size exceeded.
• 507 - user's storage quota exceeded.

{
  "id":        UUID,
  "parent_id": UUID | null,   // UUID of the group this list belongs to
  "name":      string,
  "color":     string | null, // HEX or theme token name
  "icon":      string | null, // SF Symbol
  "archived":  boolean,
  "is_owner":  boolean,       // you own the list
  "is_shared": boolean        // the list has members
}

{
  "id":       UUID,
  "name":     string,
  "color":    string | null,
  "icon":     string | null,
  "archived": boolean
}

{
  "id":            UUID,
  "list_id":       UUID | null,
  "parent_id":     UUID | null,   // for subtasks
  "title":         string,
  "note":          string | null,
  "due_at":        string | null, // ISO-8601 UTC
  "due_has_time":  boolean,
  "completed_at":  string | null, // ISO-8601 UTC
  "flagged":       boolean,
  "priority":      0 | 1 | 2 | 3,
  "rrule_freq":     0 | 1 | 2 | 3 | 4 | 5, // 0=none, HOURLY/DAILY/WEEKLY/MONTHLY/YEARLY
  "rrule_interval": number,  // >=1
  "rrule_byday":    number,  // bitmask Mon=1..Sun=64
  "rrule_bymonth":  number,  // bitmask Jan=1..Dec=2048
  "rrule_bysetpos": number,  // 1..4 or -1, 0=unset
  "rrule_end_kind": 0 | 1 | 2, // 0=never, 1=until date, 2=after N
  "rrule_until":    string | null, // ISO-8601 UTC
  "rrule_count":    number,
  "rrule_done":     number,
  "rrule_anchor":   0 | 1, // 0=schedule, 1=completion
  "in_my_day":     boolean,
  "in_my_day_date": string | null, // YYYY-MM-DD
  "sort_order":    number,
  "collapsed":     0 | 1,          // 1 = subtasks collapsed
  "files":         FileRef[],      // see "Attached files"
  "version":       string,    // ISO-8601 UTC, server-updated
  "updated_at":    string,    // ISO-8601 UTC
  "date_create":   string,    // ISO-8601 UTC
  "completed_user_id": UUID | null, // who closed it (relevant for shared lists)
  "deleted_user_id":   UUID | null  // who deleted it
}

{
  "id":         UUID,
  "list_id":    UUID,        // always attached to a specific list
  "title":      string,
  "note":       string | null,
  "sort_order": number,
  "files":      FileRef[],   // see "Attached files"
  "version":    string,      // ISO-8601 UTC
  "updated_at": string       // ISO-8601 UTC
}

{
  "id":   UUID,
  "name": string,    // original file name
  "size": number,    // size in bytes
  "url":  string     // absolute URL (https://taskid.app/files/...)
}