The infinitodo API

A plain REST API for your lists: for Zapier, Make, n8n, Home Assistant, shortcuts and your own scripts. It's part of Premium. (For AI assistants like Claude, see AI agents instead.)

Getting started

  1. In infinitodo, open Settings › API, give a token a name (what it's for, e.g. “Zapier”) and choose what it can do: Read and change, or Only read. Copy it: it's shown once.
  2. Send it with every request, as Authorization: Bearer itp_…, to https://infinitodo.com/api/v1.
curl https://infinitodo.com/api/v1/me \
  -H "Authorization: Bearer $INFINITODO_TOKEN"

Requests and answers are JSON (send Content-Type: application/json with a body). Times are ISO 8601 in UTC; dates are YYYY-MM-DD, times of day HH:MM.

Tokens and limits

  • A token acts as you: it can see your own list and your groups' lists, and what it changes shows under your name, live for everyone, in the history, and undoable like anything else.
  • Only read tokens can use GET; anything else answers 403 api_read_only.
  • Keep tokens secret. Delete one in Settings › API and it stops working at once. If your account goes back to Free, tokens stop until you're on Premium again.
  • At most 120 requests a minute per token; past that, 429 rate_limited with a Retry-After header (seconds).

Lists and item IDs

GET /lists gives your lists: mine (your own) and each group you're in. In a URL, a list is mine, a group's id, or its group ID (like HOME1) when only one of your groups has it.

Items are named by the ID shown in the app, like HOME1-00002A (any case), or by their uuid. Two of your groups can share a group ID (they have different owners); then an item ID answers 409 item_ambiguous: use the uuid.

Items

{
  "id": "HOME1-00002A",
  "uuid": "3b039ba2-aff8-4521-aebe-73e961fdd0d4",
  "list": "4f0c…",            // "mine", or the group's id
  "title": "Order seeds",
  "notes": "The heirloom ones",
  "completed": false,
  "due_on": "2026-12-01",       // or null
  "due_time": "09:30",          // or null
  "repeats": "every month",     // in words, or null
  "assignee": {"id": "…", "name": "Pat"},  // or null
  "parent": "HOME1-000027",     // or null (at the top)
  "place": "list",              // "list", "archive" or "trash"
  "url": "https://infinitodo.com/app/tasks/3b039ba2-…",
  "created_at": "2026-11-13T23:51:06Z",
  "updated_at": "2026-11-13T23:51:06Z"
}

In a list's items, each also has depth (0 at the top); in search results, path: the titles of what it's under.

Endpoints

RequestWhat it does
GET /meWho the token acts as, its plan and access.
GET /listsYour lists: {"lists": [{id, code, name, kind, role}]}.
GET /lists/:list/itemsThe list's items, in outline order (each after its parent). Not the trash or the archive. ?completed=false: only open ones. ?under=ID: just what's under an item.
POST /lists/:list/itemsAdds an item: title, and optionally notes, parent (an item ID in the same list), due_on, due_time, assignee_id (a group member; without one, the list's default assignee, if it has one). 201 with the item.
GET /items/:idOne item.
PATCH /items/:idChanges any of title, notes, due_on, due_time (null clears), assignee_id (null unassigns), completed.
POST /items/:id/complete
POST /items/:id/uncomplete
Checks it off, or back on. An item checks off once its sub-items are.
DELETE /items/:idMoves it, and what's under it, to the trash (204). It can be restored in the app.
GET /items/:id/commentsIts comments, oldest first: {id, body, author, reply_to, created_at, edited_at}.
POST /items/:id/commentsComments on it: body. In a group, you then follow it.
GET /search?q=…Matching items in all your lists, best first. An item ID finds that item.
GET /eventsA live stream of changes to your lists, for apps.
DELETE /tokenRevokes the token it's sent with, for an app signing out (any token can do this, read-only ones too).
GET /webhooks
POST /webhooks
DELETE /webhooks/:id
Your webhooks; add one (url, list, events) or delete one. For services that subscribe themselves, like Zapier.

Items in the trash or the archive can be read but not changed (422 item_not_in_list).

Examples

Add an item to your own list, due Friday morning:

curl -X POST https://infinitodo.com/api/v1/lists/mine/items \
  -H "Authorization: Bearer $INFINITODO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Renew the car insurance", "due_on": "2026-11-20", "due_time": "09:00"}'

Add a sub-item to a group's item, assigned to someone:

curl -X POST https://infinitodo.com/api/v1/lists/HOME1/items \
  -H "Authorization: Bearer $INFINITODO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Buy a new filter", "parent": "HOME1-00002A", "assignee_id": "…"}'

Check it off:

curl -X POST https://infinitodo.com/api/v1/items/HOME1-00002B/complete \
  -H "Authorization: Bearer $INFINITODO_TOKEN"

What's still open in a group's list:

curl "https://infinitodo.com/api/v1/lists/HOME1/items?completed=false" \
  -H "Authorization: Bearer $INFINITODO_TOKEN"

Webhooks

Rather than asking every few minutes, let infinitodo tell you: a webhook is a URL that infinitodo POSTs to whenever items change in a list. Add one in Settings › API (or with POST /webhooks): the URL, the list it watches (yours or a group's), and which of these it's for:

  • item.created: added (also from a playbook or an import).
  • item.updated: renamed, notes, due date, repeat, or moved.
  • item.completed, item.uncompleted: checked off, or back on (a repeating item checked off counts as completed).
  • item.assigned: assigned or unassigned.
  • item.commented: a new comment (its text comes along).
  • item.deleted, item.restored, item.archived.

Each change is one POST, JSON:

{
  "id": "7d6c…",              // this delivery
  "event": "item.completed",
  "occurred_at": "2026-11-14T15:02:11Z",
  "by": {"id": "…", "name": "Pat"},
  "item": { … },               // as in the API (see Items)
  "comment": {"body": "…"}     // item.commented only
}

Check it's from infinitodo: each delivery has an X-Infinitodo-Signature: sha256=… header, the HMAC-SHA256 of the body (as received, before parsing) keyed with the webhook's secret (shown in Settings › API), in hex. Also sent: X-Infinitodo-Event and X-Infinitodo-Delivery.

# Python
import hmac, hashlib
expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
ok = hmac.compare_digest(expected, request.headers["X-Infinitodo-Signature"])

// Node.js
const crypto = require("crypto");
const expected = "sha256=" + crypto.createHmac("sha256", secret).update(body).digest("hex");
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
  • Answer with a 2xx status within 10 seconds. Anything else is tried twice more (after 2 and 15 seconds). After 10 failed deliveries in a row the webhook is switched off; turn it on again in Settings › API, which shows what went wrong. Send a test there sends a ping.
  • The URL must be https:// and on the public internet: not a local or private network address. Redirects aren't followed.
  • Deliveries can come more than once, or out of order: use the delivery id and the item's updated_at if that matters.
  • Webhooks stop while your account isn't on Premium, or if you leave the group whose list it watches.

Live changes

Webhooks are for servers. An app that can't be reached, like one on your computer, can instead keep GET /api/v1/events open: a stream of server-sent events.

  • It starts with event: hello, whose data is {"lists": [...]}, as GET /lists gives them.
  • Then, as soon as something in one of your lists changes (an item added, changed, checked off, moved or deleted, or a comment), event: changed with {"list": "mine"} or the list's id: fetch that list's items again. One change can touch several lists.
  • A comment line (: ping) every 15 seconds keeps the connection open. If one doesn't come for a while, connect again. You'll get hello again: fetch your lists then too, in case you missed something, or joined or left a group.
curl -N https://infinitodo.com/api/v1/events \
  -H "Authorization: Bearer $TOKEN"

Errors

Anything that doesn't work answers with a status and {"error": {"code": "…", "message": "…"}}, the message in plain English:

  • 401 api_unauthorized: no token, or not a valid one.
  • 403 api_premium_required (your account isn't on Premium), api_read_only.
  • 404 item_not_found, list_not_found, parent_not_found.
  • 409 item_ambiguous, list_ambiguous: use the uuid or the list's id.
  • 422 anything about what you sent: blank_title, invalid_due, incomplete_children, not_a_member, item_not_in_list…
  • 429 rate_limited: wait for Retry-After seconds.

The API's shapes are kept stable within v1: new fields may appear, but nothing is taken away or changes meaning.