API Reference
Interactive reference for the OpenTask REST API, auto-generated from the OpenAPI 3.1 specification.
REST API for OpenTask, a self-hosted task management application.
Authentication
All endpoints require authentication via one of the methods below, except
/api/health, /api/openapi and /api/push/vapid-key (public) and
/api/notifications/actions (takes the API token in its request body):
- Bearer token —
Authorization: Bearer <token>header - Reverse proxy header — configured via
OPENTASK_PROXY_AUTH_HEADERenv var - Session cookie — set by the web UI login flow
Bearer tokens are created via POST /api/tokens or the db:create-token CLI command.
Response format
Success: { "data": { ... } }
Error: { "error": "message", "code": "ERROR_CODE", "details": { ... } }
Servers
Tasks
Operations
List tasks
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Parameters
Query Parameters
Filter by completion status (default false)
Filter by label name
Search in title and notes
true = only what is due right now, by the same definition as the
app badge, notifications and the snooze-overdue sweep: reminders
and quotas are never overdue, and a recurring task's due-ness comes
from its schedule. Only the user's own tasks (the badge's
population). Applied before pagination.
Narrow to one population: ordinary tasks, reminders
(is_reminder), or quotas (is_tracked or progress_target > 1).
Omitted = all three. Applied before pagination; any other value is
a 400.
"task""reminder""quota"2000Responses
List of tasks
Samples
Create task
Send a raw title string for AI enrichment, or provide structured fields
to bypass enrichment. AI enrichment triggers when only title is provided
(no due_at, priority=0, no labels, no rrule).
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Created task
Samples
Counts for the nav badges
{ total, overdue, today } over the user's active tasks — the same
numbers the Tasks page shows in its top bar, computed with the same
function, for pages that do not load the list.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
Task counts
Samples
Get task
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
Task details
Samples
Delete task (soft delete to trash)
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
Trashed task
Samples
Update task
PATCH semantics — only fields present in the body are updated.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Updated task with change metadata
Samples
Mark task done
For recurring tasks, advances due_at to the next occurrence.
For one-off tasks, sets done=true and archives.
Quotas are refused (400) unless the body has close_period: true.
Completing a quota closes its period early and resets
progress_current to 0; to log one, use
POST /api/tasks/{id}/progress. The body is optional — a bare POST
with no body works for everything else.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Completed task
Samples
Mark task undone (reopen / put back)
One-off task: reopens it. Recurring task: puts back its most recent
completion — the occurrence returns to the due date it had and the
completion counts roll back one. Refuses (400) when the task's due date
has changed since that completion, or when there is nothing to put back.
Logged as an undoable action either way.
Refuses (400) a quota (2026-09-24): a quota's completions are the period
rollover's record of a met period, and putting one back deleted that
record while the period stayed closed. Correct a count with
POST /api/tasks/{id}/progress and delta: -1 instead.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
Reopened task
Samples
Log progress on a tracked task
Records progress on a task with progress_target > 1 (REDESIGN-V03 §5).
A sub-target increment is NOT a completion: it dispatches
task.progressed, never task.completed, and the task stays open until
its period boundary. Returns 400 if the task is not tracked.
If the quota's period has ended but the rollover job has not run yet
(it runs every few minutes), the period is closed first, so a +1 just
after midnight counts for the new day. Progress logged today is also
recorded in the quota's quota_day_state (it clears a weekly/monthly
quota prompt for the day); undo restores both.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Updated task
Samples
Skip this occurrence without completing it
"Not doing this occurrence - advance without recording a completion"
(REDESIGN-V03 §7.5).
Recurring tasks advance to the next occurrence with completion_count
untouched and skip_count incremented. One-off tasks are archived
without being marked done. Dispatches task.skipped, never
task.completed.
Named skip-occurrence rather than skip because the review API
already uses "skip" for a no-op review acknowledgment.
Reminders (is_reminder) are refused (400): a missed one already
rolls forward on its own, and completing one marks it considered.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
Skipped task
Samples
Confirm an assistant-proposed task
Swaps the ai-proposed provenance label for ai-added (REDESIGN-V03
§7.2). Task-scoped and narrow: confirming is a statement about where a
task came from, so nothing else is modified. Idempotent.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
Confirmed task
Samples
Snooze task
Moves a task's target (due_at) — the same move as PATCH { target_at }
(2026-10-12, spec §6: there is no snooze state). It stops at the task's
deadline while that deadline is still ahead (spec §8.2): the response's
capped_at_deadline is true when it did. Once the deadline has passed
the cap is off and any target can be picked (2026-10-12).
allow_past_deadline and cap_at_deadline are accepted from
old clients and change nothing. Two populations refuse it with a 400,
because neither has a due date to move: reminders (§6), which stay in
their time slot until completed, and quotas (§5), which are counted
within a period rather than due on a day. The bulk snooze sweep skips
both instead of failing.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Snoozed task
Samples
Restore task from trash
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
Restored task
Samples
Retry AI enrichment
Re-runs AI enrichment using the original_title.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
Task queued for reprocessing
Samples
What Process works through
The in-app Process button's lists, computed by rule (no AI, so it works with AI off). Read-only: Process writes through PATCH, bulk edit (affirm_horizon, target_at: null — on a deadline task that is Back to auto), target-today and DELETE. Only the caller's own open tasks, never reminders or quotas; growth and the stale-target lists also leave out recurring tasks.
inbox: tasks still in the Inbox project, oldest first, recurring ones included (the
dashboard's Inbox group, so the two counts agree).growth: tasks long past their horizon, longest first. Measured fromhorizon_set_at, else
created_at; days after 14 days, weeks or unset after 60, months after 180 (eventually never).
Asks for the next horizon up. Excludes tasks whose target has arrived (they are in the old-target
lists or on the dashboard) and tasks whose deadline is close enough to steer the horizon (90 days
or past).fromis null for an unset horizon.can_act(priority 2+) offers "do it" / "raise
priority" beside "grow".stale_targets: tasks whose target arrived 7+ days ago (age_days, measured from the first
target, so snoozing does not reset it), oldest first.stale_targets_with_deadline: the same for tasks with a deadline, listed apart so a client's
nag is never stopped by default.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
Process lists
Samples
List registered labels
The label registry (REDESIGN-V03 §7.2). Labels used to be bare
free-text, so a typo silently forked the taxonomy. Creating a label is
now a discrete act: a task write carrying an unknown label is rejected
unless it also carries create_label.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
Registered labels
Samples
Register a label
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
The registered label (idempotent - returns the existing row if present)
Samples
Deregister a label
Removes the label from the registry. Does NOT strip it from tasks that
already carry it - §7.2 checks only NEWLY added labels, so those tasks
stay editable; the label simply can't be applied to anything new.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
Deleted
Samples
Time slots
List time slots
Life-moment containers - "Early morning", "Before work", "Evening"
(REDESIGN-V03 §6.0). The dashboard and the Reminders surface group by
this same table, so "morning" means one thing across the app.
An item belongs to the slot with the latest start_time <= its time of
day, where time of day is anchor_time if set, else due_at read in
the user's timezone.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
Time slots, earliest first
Samples
Create a time slot
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
The created slot (start_time must be unique among the user's slots)
Samples
Remove a time slot
Removes the slot and moves each of its reminders to the start of the
remaining slot nearest the reminder's own time of day (a tie goes to the
earlier slot), so none drop out of every slot. Quota prompts placed in
the slot move the same way (2026-09-25): every stored prompt period
naming it — a quota's quota_prompt_config.slot_id and per-number
overrides, and the user's default prompt period — is repointed to the
remaining slot nearest the removed slot's start (quotas_moved). The
last remaining slot cannot be removed (400). Always an undo entry
(time_slot_delete, undo_id): undo restores the slot under its
original id together with its reminders and prompt placements.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
The removed slot, as it was
Samples
Rename a time slot and/or move its start
Settings → Reminder periods. A reminder belongs to a slot only through
its time of day, so moving a slot's start_time also moves that slot's
reminders to keep them in it: reminders on the old start move to the new
start, reminders inside the slot keep their time unless the new
boundaries would put them in another slot (then they move to the new
start). Other slots' reminders and ordinary tasks are never touched.
The slot change and the reminder moves are one atomic undo entry
(time_slot_edit) that also restores the slot; undo_id names it.
A rename alone moves nothing and returns undo_id: null.
start_time must be unique among the user's slots. There is no
reordering: slots are always ordered by start_time.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
The slot after the change
Samples
Mark multiple tasks done
Quotas in ids are skipped (counted in quota_skipped) unless
close_period: true — completing a quota closes its period early and
resets its count. A batch of nothing but quotas is a 400.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Bulk operation result
Samples
Snooze multiple tasks
Snoozes one or more tasks. Supports absolute mode (until) or relative
mode (delta_minutes) — exactly one must be provided.
Priority filtering, by default:
- P0-P2 are always snoozed.
- P3 (High) is snoozed ONLY when no lower-priority task in the same
batch is still eligible. A mixed batch clears P0-P2 and leaves the
High tasks; the next call, finding only High left, takes them. A P4 in
the batch does not hold this back, since a P4 is never swept. - P4 (Urgent) is never snoozed by a sweep — its due date is a hard
deadline and every change to one has to be deliberate. - A task whose DEADLINE HAS PASSED is read as at least P3 (2026-10-12):
it waits while any P0-P2 task without a passed deadline is still
eligible, and goes with the High tier after. A P3 with a passed
deadline is still P3; a P4 is still never swept. Those held back
only by the deadline are counted inskipped_deadline(not in
skipped_urgent).
Callers that represent an explicit user selection (e.g., the mobile
selection sheet's quick panel) should pass include_task_ids so the
listed high/urgent tasks are snoozed anyway.
skipped_urgent keeps its name for client compatibility and counts BOTH
P3 and P4 skips. skipped_high is the P3 subset of it, so a client can
name the two tiers accurately; Urgent alone is the difference.
Each eligible task is changed exactly as PATCH /api/tasks/{id} with
{ due_at } would change it: a dated task's target moves (its
first-target date kept), stopping at a deadline still ahead
(capped_deadline; a passed deadline caps nothing); a
task with no date (absolute mode only) gets its
first date, which is not counted as a snooze; a task already due at
the target is left alone. tasks_affected counts only the tasks whose
date actually moved, so it plus tasks_skipped can be less than the
number of ids.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Bulk operation result
Samples
Snooze all overdue tasks
Snoozes all overdue tasks that the priority rule allows: P0-P2 always,
P3 (High) once no lower-priority task in the batch is still eligible,
and P4 (Urgent) never. See /api/tasks/bulk/snooze for the full rule
and for what skipped_urgent and skipped_high count.
The target is at most one of until, delta_minutes, slot or
tomorrow; with none, the user's default snooze option applies.
Feedback notification. When the call is authenticated with an API
token (not a browser session) and the sweep leaves High or Urgent tasks
overdue, the server sends one quiet push notification to the user's
devices saying how many of each stayed overdue (counts only, never
titles). It is not sent when nothing High or Urgent is left, when the
user has turned off sweep_feedback_notifications_enabled or
notifications as a whole, or when the request says notify: false.
A newer result replaces the older notification.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Bulk operation result
Samples
Edit multiple tasks
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Bulk operation result
Samples
Soft-delete multiple tasks
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Bulk operation result
Samples
Complete multiple tasks in one request
Built for the §6.1 notification batch checklist: the iOS content
extension commits N staged check-marks with one request. Delegates to
the same core bulk-done path — one transaction, ONE undo entry.
Quotas are skipped unless close_period: true, as for
/api/tasks/bulk/done (and refused when nothing else is in the batch).
Quota prompts (2026-09-24): prompts acts on quota prompts in the SAME
transaction and undo entry — a checklist commit or a slot's "Considered
all" mixing reminders and prompts is one Undo. Each entry is a
prompt_key string (consider it) or { key, did } (did: true = the
square checkbox: log progress and consider it). A quota is acted on
through its prompt, never completed by id. ids may be empty when
prompts is not. A stale-date or foreign key refuses the whole batch.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Completion result
Samples
Consider quota prompts (no progress)
The round circle on a quota prompt: handled for today, nothing logged.
One transaction and one undo entry for every key; idempotent. Keys come
from GET /api/reminders groups[].prompts[].prompt_key; a key for
another local day, or for a quota that is not the caller's own, refuses
the whole request (400).
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
What the prompt action did, and the quotas it touched
Samples
Did it — log progress on quota prompts
The square checkbox on a quota prompt: logs progress AND considers the
prompt. Idempotent per key, so a double tap or a retry logs once: a
daily quota's prompt k raises today's count to at least k; any
other quota gets +1 unless that key was already done today. One
transaction, one undo entry; undo restores the count and the prompt.
Dispatches task.progressed for each quota whose count moved.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
What the prompt action did, and the quotas it touched
Samples
Put back handled quota prompts
The filled dashed circle on a handled prompt in a "considered" / DONE
list (2026-09-25): the prompt waits for today again. Its key leaves
today's considered and did; if it was "did it", exactly the
progress that did-it added is taken back (quota_day_state.did_applied
— a daily prompt k done when the count was already at k added 0,
so it takes back 0). Any other did-it the lower count no longer
supports waits again too. A key that is already waiting changes
nothing. One transaction and one undo entry (always logged, so a
toast's Undo never reaches an older action). Keys for another local
day, or for a quota that is not the caller's own, refuse the whole
request (400). Quotas are never put back with /api/tasks/{id}/undone.
Dispatches task.progressed for each quota whose count moved.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
How many prompts now wait again, and the quotas touched
Samples
Mark task-segment rows considered
The circle: stamps last_considered_at. Never a completion. One undo entry; logged even when already considered today. The caller's own open tasks only; anything else refuses the whole request (400).
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Done
Samples
Defer task-segment rows to tomorrow
Defer All: stamps segment_deferred_at; off today's segment, back tomorrow. Not a consider. One undo entry. The caller's own open tasks only; anything else refuses the whole request (400).
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Done
Samples
Put task-segment rows back
The put-back behind "Show N considered" (2026-10-11): clears last_considered_at and segment_deferred_at, so each row waits in its segment again today and comes back daily until it is considered. One undo entry. The caller's own open tasks only; anything else refuses the whole request (400).
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Done
Samples
Target tasks today
A move of the target (a target the user picked) to the Snooze-all button's time while still today — the next period or the default snooze option — else the top of the next hour; or to at, when given. Also marks them considered and stamps segment_targeted_at. One undo entry (bulk edit) puts back the target and both stamps. Like every move it stops at the task's deadline (2026-10-12, spec §8.2). The caller's own open tasks only; anything else refuses the whole request (400). REPEATING tasks (an rrule) are targeted too since 2026-10-12 (spec §6): only the target moves, the scheduled occurrence (occurrence_at) stays, so done that day brings the next occurrence round on schedule.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Done
Samples
Today's incomplete reminders grouped by time slot
The Reminders surface (prompted thoughts, not actions). Items carry no
debt: never counted in overdue, never in the badge, never notified
individually — the time slot notifies. A reminder completed today
drops out of its group and returns with its next occurrence.
QUOTA PROMPTS (2026-09-24). Every unmet quota also appears as a prompt
in a period each day, in the SEPARATE groups[].prompts array.
reminders, count, considered, total and considered_total stay
reminder-only, exactly as before, so clients that predate prompts are
unaffected. prompts holds every prompt assigned to the slot today,
handled ones included; a prompt is waiting while !considered && !done, and a client counts it like a reminder (waiting, then
considered). Act on one with POST /api/quota-prompts/consider,
/did, or prompts in POST /api/tasks/bulk/complete. The user's
quota_prompts_enabled preference and the server's
OPENTASK_QUOTA_PROMPTS=off each make every prompts array empty.
The slot notification and its nags count waiting prompts too, so a
client's slot checklist should list them after the reminders.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
Reminder groups in slot order
Samples
Every open quota for the user
The Quotas surface. A quota is "how often", not "when" — four workouts a
week, one date night a month — and is a task carrying progress_target
greater than 1 OR is_tracked true. The flag exists so a target of one
can still be a quota rather than a deadline.
A quota has NO due date (since 2026-09-08): due_at and
original_due_at are always null, creating or updating one with a date
is a 400, and snoozing one is a 400. "Four times this week" cannot be
late on a Tuesday. The period a quota counts within is named by its
rrule's FREQ, and the current period's start is progress_period_start
on the task — that field is the period anchor; use it, not due_at, for
pace.
A quota is also absent from GET /api/tasks-backed list surfaces in the
app — it appears on this endpoint and in the Track panel and nowhere
else — but GET /api/tasks itself still returns quotas, so clients that
build their own Track view from the full corpus keep working.
Order is deliberately NOT specified here. Clients sort quotas
alphabetically so that logging progress on one never reorders the others
under the user's finger.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
The user's open quotas
Samples
List projects
The user's own projects plus projects shared with them.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
List of projects with task counts
Samples
Create project
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Created project
Samples
Reorder projects
Sets each project's sort_order to its position in project_ids
(0, 1, 2, ...). Only projects the user owns are reordered; ids of
shared projects owned by someone else, or unknown ids, are ignored and
the remaining owned projects keep their relative order.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Number of projects reordered
Samples
Get project
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
Project details
Samples
Delete project
Permanently deletes the project and moves each of its tasks to its
owner's Inbox (in a shared project, every member's tasks go to that
member's own Inbox). Not undoable. The Inbox itself cannot be deleted (400).
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
Deletion result
Samples
Update project
Owner only. The Inbox cannot be renamed (400); its other fields can change.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Updated project
Samples
Undo last action
Reverses the most recent undoable action. The body is optional; send
session_start_id to have the returned counts cover only entries after
that id (see GET /api/undo/status) instead of all time.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Undo result
Samples
Redo last undone action
Re-applies the most recently undone action. The body is optional; send
session_start_id to scope the returned counts, as for POST /api/undo.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Redo result
Samples
Undo stack status
The newest undo-log id and how many entries can be undone and redone.
A client can store latest_id when it starts and pass it back as
session_start_id to scope undo to its own session.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
Undo stack status
Samples
Undo history
The user's most recent undo-log entries, newest first, both undone and not.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Parameters
Query Parameters
150Responses
Undo history
Samples
Undo several actions
Undoes entries from the top of the stack, newest first, in one
transaction: all of them are undone or none are. Provide at least one
of the fields; when several are given, every limit applies.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Batch undo result
Samples
Redo several actions
Redoes undone entries, oldest undone first, in one transaction.
Provide at least one of the fields.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Batch redo result
Samples
List trashed tasks
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Parameters
Query Parameters
200Responses
Trashed tasks
Samples
Empty trash (permanent delete)
Permanently deletes all trashed tasks. Cannot be undone.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
Number of tasks permanently deleted
Samples
Export user data
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Parameters
Query Parameters
"json""csv""json"Required for CSV format. Each table is a separate file.
"tasks""projects"Responses
Exported data
Samples
List webhooks
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
User's webhooks (secrets excluded)
Samples
Create webhook
Creates a webhook with an auto-generated HMAC secret.
The secret is returned in this response only — store it securely.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Created webhook with secret (shown once)
Samples
Delete webhook
Update webhook
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Updated webhook (secret excluded)
Samples
List recent webhook deliveries
Returns the last 50 delivery attempts for debugging.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
Delivery history
Samples
List API tokens
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
API tokens (previews only, not full tokens), newest first
Samples
Create API token
Creates a new API token. The full token is returned in this response only.
Tokens are stored as SHA-256 hashes — the raw token cannot be retrieved later.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Created token (shown once)
Samples
Revoke API token
Exchange a Bearer token for a web session cookie
Mints a NextAuth session cookie for the owner of the supplied Bearer token and
returns it in a Set-Cookie header. Used by the iOS app to log its WKWebView back
in when the 7-day session JWT expires, using the long-lived token in its keychain.
Bearer authentication only — a missing, malformed, or invalid Authorization
header returns 401. This endpoint never falls back to session cookie or proxy
header auth.
The cookie is HttpOnly, SameSite=Lax, Path=/, expires in 7 days, and is named
__Secure-authjs.session-token over HTTPS (authjs.session-token otherwise).
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
Session cookie issued
Samples
Current user
The authenticated user's identity and core settings. Useful to check which account a token belongs to.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
The authenticated user
Samples
Get user statistics
Without start and end, returns a summary (today, this week, this
month, all time). With both, returns { stats: [...] }, one row per
day that has stats in the range, oldest first.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Parameters
Query Parameters
Start date for daily stats range (YYYY-MM-DD)
"date"End date for daily stats range (YYYY-MM-DD)
"date"Responses
Stats summary or daily stats for date range
Samples
Query completion history
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Parameters
Query Parameters
Filter by completion date (YYYY-MM-DD, UTC calendar date)
"date"Filter to completions at or after this instant. Must be paired with until.
"date-time"Filter to completions before this instant. Must be paired with since.
"date-time"Responses
Completion records
Samples
Get the user's preferences
The signed-in user's settings. Only week_start is described field by
field here; the response carries the rest of the Settings page's
values (view, snooze, schedule, notification and AI settings) as well.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
The user's preferences
Samples
Update the user's preferences
Send only the fields to change. Changing week_start closes, before
the response is returned, any weekly quota period the new boundary has
already ended (see UserPreferences.week_start).
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
The user's preferences after the update
Samples
Start a review session
Numbers the user's overdue tasks and tasks due within the next 24
hours (overdue first, then by due date) so a client can act on them by
number with POST /api/review/execute. Sessions are held in server
memory: one is discarded once executed, sessions older than an hour
are purged when a new one starts, and all are lost on a server restart.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
The review session
Samples
Act on a review session
Applies actions to tasks by their seq numbers from GET /api/review.
Actions run in order, each as its own bulk operation (and undo entry);
they are not one transaction. The whole body is validated first, so a
snooze without until is a 400 before any action runs. Review
targets are explicit picks: snooze moves High and Urgent targets too,
where a sweep would hold them back. The session is discarded afterwards.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
What each action did
Samples
AI status and activity
Diagnostics for the AI features: the state of the warm model slots and
request queue (server-wide), work in progress for this user, and the
user's recent AI activity log. The slot objects use camelCase keys.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Parameters
Query Parameters
Activity entries to return.
201000Only activity entries of this action.
"enrichment"Responses
AI status
Samples
Test an AI feature's model
Sends a minimal prompt through the provider and model configured for
one feature, to check that it responds. A provider failure is reported
in the 200 body (success: false, error), not as an HTTP error.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Test result
Samples
Quick take on a new task
A one-line AI comment on a task title, in the context of the user's task list.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
The quick take
Samples
What's Next recommendations
Returns today's cached recommendations. Without refresh=true this
never generates: when nothing was generated today (UTC) data is
null. With refresh=true it runs the model and waits for the result.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Parameters
Query Parameters
Generate fresh recommendations now.
Responses
Recommendations, or null
Samples
Start Insights generation
Scores all of the user's active tasks in the background and returns at
once. Poll GET /api/ai/insights/status with the returned
session_id, then read GET /api/ai/insights/results.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
Generation started. With no active tasks, session_id is null,
total_tasks is 0 and message says so.
Samples
Insights generation progress
Works whether or not AI is enabled (it only reads the stored session).
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Parameters
Query Parameters
Responses
Session progress
Samples
Insights results
The latest Insights scores for the user's tasks, highest score first,
with the signal vocabulary for display. Works whether or not AI is
enabled (it only reads stored results).
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
Insights results
Samples
Recommend a project for each task
For the Process button's sorting step: the project each given task
probably belongs in, or null when none clearly fits. The AI only
recommends — nothing is written; the user picks. It reads each
project's description (what belongs there) and the user's global
ai_context.
Ids that are not the caller's own live tasks are ignored. A
project_id is always one of the caller's own or shared projects,
never the Inbox; a model answer naming any other project is dropped,
so a task can be missing from recommendations (no recommendation).
Entries follow the order of ids.
AI disabled (server-wide, or the user's Insights mode set to off)
returns { recommendations: [] } with 200, never an error. Uses the
Insights feature's AI mode, model and timeout.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Recommendations (empty when AI is off)
Samples
Possible duplicate tasks
For the Process button's duplicate step: groups of the caller's open
one-off tasks (not recurring tasks, reminders or quotas) that look like
the same piece of work. Each group has 2+ task ids and a task is in at
most one group. Nothing is written. Scans the newest 600 such tasks.
AI disabled (server-wide, or the user's Insights mode set to off)
returns { groups: [] } with 200, never an error.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
Duplicate groups (empty when AI is off or none were found)
Samples
Act on a task from a notification
Done, snooze or delete for a single task, as sent by notification
action buttons. The API token goes in the body, not the Authorization
header, because the iOS notification extension cannot set headers.
done— mark the task donesnooze30— snooze 30 minutes from nowsnooze— snooze 1 hour from now, rounded to the hoursnooze2h— snooze 2 hours from now, rounded to the hourdelete— move the task to the trash (a soft delete, undoable like
any other delete; the "AI finished" notification's Delete button).
A task already in the trash is a 400.
Request Body
Responses
The action taken. result is the task operation's own result: its
task is the stored task, without the computed is_recurring and
target_at fields.
Samples
Dismiss all notifications
Clears the user's delivered notifications on every channel and device.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
Dismissal sent
Samples
Send a test notification
Creates a real task (labelled test, due a minute ago) and, about 3
seconds later, sends a notification for it to every configured
channel (Web Push and APNs), so Done and Snooze can be tried end to
end. high sends a High (P3) notification; urgent and critical
both send an Urgent (P4) one as an Apple Critical Alert, the same as a
real overdue P4.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Test scheduled
Samples
Web Push public key
Send a test Web Push notification
Sends a test notification to the user's Web Push subscriptions only.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
Whether it was sent
Samples
Register an APNs device
Registers an Apple device token for push notifications. Re-registering
an existing token moves it to the calling user.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Registered
Samples
Unregister an APNs device
Removes the device token, whichever user registered it.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Unregistered
Samples
Register a widget push token
Registers a WidgetKit push token (a widget extension's token, separate
from the app's device token) so the server can tell widgets to reload
when the user's data changes. Re-registering a token moves it to the
calling user.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Registered
Samples
Unregister a widget push token
Removes the push token, whichever user registered it.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Unregistered