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
- 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.
-
Send it with every request, as
Authorization: Bearer itp_…, tohttps://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 403api_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_limitedwith aRetry-Afterheader (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
| Request | What it does |
|---|---|
GET /me | Who the token acts as, its plan and access. |
GET /lists | Your lists: {"lists": [{id, code, name, kind, role}]}. |
GET /lists/:list/items | The 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/items | Adds 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/:id | One item. |
PATCH /items/:id | Changes any of title, notes, due_on, due_time (null clears), assignee_id (null unassigns), completed. |
POST /items/:id/completePOST /items/:id/uncomplete | Checks it off, or back on. An item checks off once its sub-items are. |
DELETE /items/:id | Moves it, and what's under it, to the trash (204). It can be restored in the app. |
GET /items/:id/comments | Its comments, oldest first: {id, body, author, reply_to, created_at, edited_at}. |
POST /items/:id/comments | Comments 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 /events | A live stream of changes to your lists, for apps. |
DELETE /token | Revokes the token it's sent with, for an app signing out (any token can do this, read-only ones too). |
GET /webhooksPOST /webhooksDELETE /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
2xxstatus 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 aping. -
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
idand the item'supdated_atif 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": [...]}, asGET /listsgives 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: changedwith{"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 gethelloagain: 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 forRetry-Afterseconds.
The API's shapes are kept stable within v1: new
fields may appear, but nothing is taken away or changes meaning.