Integrations

TodoHen, connected.

A REST API for your scripts, an MCP endpoint for AI assistants, calendars you subscribe to, links that open the apps, and a way in for the tasks you keep elsewhere.

API tokens

One token, made by you.

The REST API and MCP both sign in with an API token: a long-lived key that belongs to your account.

  1. Open Settings, then Account & Sync in the phone apps, or Account on the Mac and the web.
  2. Choose Create API token. On the web, give it a name that says what it is for.
  3. Copy the token, which begins cad_. It is shown once and cannot be shown again, because the server keeps only a hash of it.

Send it with every request as a bearer token. Treat it like a password: anyone who has it can read and change your tasks. The tokens your account has are listed on the web, in Settings › Account under For developers, each by its name with when it was made and last used: Remove retires one. A token can also retire itself: send it once more to POST /auth/logout, which revokes the token used.

A token acts without two-step sign-in, and is not signed out when your devices are. It cannot change your password, your email address or two-step sign-in, and it cannot buy or change a plan: those ask for someone who has signed in.

Authorization: Bearer cad_…

REST API

Your tasks, over HTTP.

Plain JSON in and out. A change made through the API reaches your devices by ordinary sync, and follows the same rules as the apps.

RequestWhat it does
GET /api/tasksLists and searches tasks. filter is open (the default), today, overdue, completed or all; list narrows it to one list, by name or id; query, tag, priority, from, to, limit and offset are described below.
POST /api/tasksCreates a task. title is required; note, due, end, priority, list, tags, repeat, reminders and subtasks are optional.
GET /api/tasks/:idReturns one task.
PATCH /api/tasks/:idChanges the fields you send, and only those. Also takes completed and pinned.
DELETE /api/tasks/:idMoves the task to the Trash, where it can still be restored in the apps.
GET /api/listsLists your lists, the Inbox first, each with its id and name.
GET /api/progressYour progress: level and points, streak, daily goal, the counts by day, weekday and hour, and every achievement with how far along it is.
GET /api/progress/statsHow productive you have been over a span of days. period is today, week, last_week, month (the default), last_month, year, last_year or all; or give from and to as dates. Answers the tasks completed, the average a day, each day of the week with its average, the busiest hours, the best days, and the count by day or by month.
Create a task
curl -X POST https://todohen.illbytes.com/api/tasks \
  -H "Authorization: Bearer cad_…" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Send invoice to Northwind",
    "due": "2026-10-16",
    "priority": "medium",
    "list": "Work",
    "tags": ["finance"]
  }'
The answer: 201, and the task as it is stored
{
  "id": "6f1c2a0e-…",
  "listId": "b9d4…",
  "title": "Send invoice to Northwind",
  "note": "",
  "priority": 3,
  "dueAt": 1792108800000,
  "endAt": null,
  "allDay": true,
  "tags": ["finance"],
  "status": 0,
  …
}
What is due today
curl "https://todohen.illbytes.com/api/tasks?filter=today" \
  -H "Authorization: Bearer cad_…"
Mark a task as done
curl -X PATCH https://todohen.illbytes.com/api/tasks/6f1c2a0e-… \
  -H "Authorization: Bearer cad_…" \
  -H "Content-Type: application/json" \
  -d '{"completed": true}'

Dates

due is YYYY-MM-DD for an all-day task, or a date and time (2026-10-16T09:00) for one with a time. end makes the task span a period; for an all-day task it is the last day covered. An empty due clears the date, and the repeat and reminders with it.

Priority, list and tags

priority is none, low, medium or high. list is a list’s name or id. Tags are tidied as the apps tidy them: lowercase, no #, spaces turned into hyphens.

Finding tasks

GET /api/tasks takes query (words that must all be in the task’s title, note, subtasks or tags), tag, priority, list, and from and to for the days its date lies between. limit and offset give a part of a long list, and the header X-Total-Count says how many match in all.

Repeats

repeat is daily, weekly, weekdays, monthly, yearly, every 3 days (or weeks, months, years), or a rule such as FREQ=WEEKLY;INTERVAL=2;BYDAY=MO,TH; none stops it. Completing a task that repeats does what the apps do: this occurrence is kept as a finished task, and the task moves to its next date.

Reminders

reminders is the list as it should be: minutes before the task is due (0 is on time), or "15m", "2h", "1d". For an all-day task, "on the day" and "1d" are at 9:00 on the day and the day before. Reminders sound on your phone and computer, once they have synced.

Subtasks

subtasks is the list as it should be: each a title, or { "id", "title", "done" }. One with the id of a subtask the task has keeps or changes it; one without is new; one left out is removed.

What comes back

Tasks come back as they are stored: times as Unix milliseconds, priority as 0, 1, 3 or 5, status as 0 open, 1 done or 2 won’t do. An error is JSON with an error message.

Dates are read in your account’s time zone: the one your browser or app last reported. A date and time that says its own zone (2026-10-16T09:00:00+01:00) is taken at its word, and timezone (in the address or in what you send, such as Africa/Lagos) reads one request’s dates in another. A task created with a time gets an “on time” reminder, as it would in the apps. Add view=summary to a GET to have dates, repeats and reminders in words, as the MCP tools give them.

Your plan’s limits apply to what the API adds: more subtasks or reminders on a task than it holds are answered 403 with needs naming the limit.

API tokens are something a plan holds, and Pricing shows which plans do. On a plan without them, Create API token says so, and a request made with a token is answered 403 with { "error": "…", "needs": "api" }.

MCP

For AI assistants that speak MCP.

TodoHen has a Model Context Protocol endpoint. An assistant that supports MCP, pointed at it with your API token, can read and manage your tasks through six tools.

The endpoint is https://todohen.illbytes.com/mcp. It speaks Streamable HTTP, keeps no session, and takes the same bearer token as the REST API.

What the assistant does with your tasks is between you and the assistant: TodoHen answers its calls, and nothing in TodoHen itself is run by an AI.

Adding it to Claude Code
claude mcp add --transport http todohen \
  https://todohen.illbytes.com/mcp \
  --header "Authorization: Bearer cad_…"
ToolWhat it does
list_tasksLists or searches tasks: open (the default), today, overdue, completed or all; by words, a tag, a priority, a list, or the days between. Fifty at a time, with how many match in all.
get_taskOne task in full: its dates, repeat, reminders and subtasks.
create_taskCreates a task from a title and, if given, a note, a due date, an end, a priority, a list, tags, a repeat, reminders and subtasks.
update_taskChanges the fields given, and only those. It can also complete or pin a task.
complete_taskMarks a task as done. One that repeats moves to its next date, with this occurrence kept as done.
delete_taskMoves a task to the Trash.
add_subtaskAdds one subtask to a task.
update_subtaskTicks or unticks one subtask, renames it, or removes it.
get_progressHow you are doing: level, streak, daily goal, achievements, and how productive you have been this week, this month, this year, ever, or between two dates, with which days of the week and which hours are your best.
list_achievementsYour achievements: those earned, and how far along the rest are.
list_listsLists your lists.

Calendar subscriptions

Your other calendars, beside your tasks.

Subscribe to any iCalendar (.ics) address and its events appear in TodoHen’s calendar, in a colour you choose.

In Settings, open Calendar Subscriptions (or Calendars on the Mac and the web), choose Add calendar, and give it a name and an address. A Google or Outlook calendar’s secret address works, and so does a public holiday feed.

https://calendar.example/holidays.ics
webcal://calendar.example/work.ics

An address that starts webcal:// is read as https://. Feeds are fetched when you save a subscription, when the calendar opens (at most every 30 minutes) and when you ask. Events are for reading: they cannot be edited from TodoHen.

The list of calendars you subscribe to syncs between your devices. The events do not, and the server does not keep them: each device fetches the feed for itself.

The Calendars settings on a Mac with two subscriptions, Holidays and Work calendar, each showing how many events it has and its address.

The phone and Mac apps fetch a feed straight from its address. A page in a browser may only talk to the server it came from, so for the web app the server fetches the feed and passes it on. Subscribed calendars are something a plan holds: Pricing shows which plans do.

Import

From the app you use now.

TodoHen reads the files other task managers let you export: TickTick, Todoist, Notion and Microsoft To Do, and any CSV with one task per row.

There is no connection to the other service and no sign-in to it. You export a file there, choose it in TodoHen’s settings, under Import on the Mac and the web and Integrations & Import on a phone, and see a summary before anything is saved.

A plain CSV needs nothing more than a first row that names its columns:

Title,Due,Priority,Tags,List
Renew passport,2026-10-20,high,errands,Personal
Book flights to Lisbon,2026-10-17,high,,Travel ideas
Buy bread and milk,today,,errands,Shopping

A whole TodoHen account can be saved and brought back too. In Settings › Account, Export my data writes one .zip with every record and attachment, and Import an export reads it into the same account or another. How it works

What comes over from each app

The Import summary on a Mac: 17 tasks in 4 lists, with a switch to include finished tasks and a note of what is left out.