API Documentation
The todoless API lets you read and organize your family’s tasks and shopping lists programmatically — building your own integrations, automations and companion tools. This documentation describes the real, public surface of the todoless backend.
Base URL
todoless is self-hosted. The API lives under /api/ on your instance:
BASE_URL = http://YOUR_TODOLESS_HOST:7070Replace YOUR_TODOLESS_HOST with your own instance host (a domain or LAN address). All examples in this documentation are illustrative.
Authentication
Two ways to authenticate, both sent as an Authorization header:
- Session: log in with email + password to receive a JWT (see Authentication).
- Personal API token: a scoped token issued to family members by family administrators (prefix tl_). Keep it secret.
At a glance
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /api/hook-health | public | No authentication. Useful for uptime / health checks. |
| GET | /api/setup-status | public | Lets onboarding UIs know whether the first account still needs to be created. |
| GET | /api/validate-invite | public | Checks that a code is unused and unexpired. Returns basic family info so the invitee can confirm before joining. |
| POST | /api/register | public | The first account bootstraps a family and becomes its admin (role admin). Later signups require a valid invite_code and join the inviter's family as member. Password must be at least 8 characters. |
| GET | /api/entries | auth | Returns combined tasks and shopping items. Personal API tokens require entries:read, tasks:read or groceries:read. |
| POST | /api/v1 | auth | Documented actions: list, filters (read), create, update, complete, assign, delete, add_subtask (write/delete). Administrative actions (role/block/delete-user) are NOT part of the public API. |
| POST | /api/tasks | auth | Creates a task in the caller's family. labels[] are validated against family/visibility rules. Personal API tokens require tasks:write. |
| POST | /api/tasks/{taskId}/subtasks | auth | The parent task must belong to the caller. The parent's subtask_ids list is updated. |
| PATCH | /api/tasks/{taskId} | auth | Updatable fields: title, status, description, assigned_to, labels, due_date, priority, horizon, flag, blocked, archived. Setting status to 'done' stamps completed_at. Non-owners get 404 (resource hidden). |
| PATCH | /api/subtasks/{subtaskId} | auth | Owner-only, like the parent task endpoints. |
| POST | /api/groceries | auth | Creates a shopping/grocery item in the caller's family. Personal API tokens require groceries:write. |
| PATCH | /api/groceries/{itemId} | auth | Updatable fields: title, completed, quantity, shop_id, assigned_to, due_date, priority, labels. Non-owners get 404. |
Guided reading
- Getting started — create your instance account and make your first call.
- Authentication — session tokens and personal API tokens.
- Tasks, Groceries, Entries, Calendar, Collections — endpoint groups.
- Errors — error format and common codes.
- Examples — copy-paste curl examples.
- OpenAPI reference — machine-readable spec.