Tasks (markdown outliner, in development) (part 10)
Tasks' local control server (127.0.0.1:19519) runs the shared feature gate in every handler and answers 403 disabled: true — not 404 — while Tasks is off, so a 404 there means only a missing id. Send plain local times; never convert to UTC yourself. The markdown mirror is a one-way, best-effort copy; the database is the source of truth.
On this page
What it is
Part 10 of Tasks (markdown outliner, in development): the CLI route reference, the markdown mirror, the gating mechanism and the time fields, split off because one page is capped at 40,000 characters.
Where to find it
Reach it from Tasks (markdown outliner, in development), which lists every part and says where the feature lives. Everything below is reached from there; the routes are CLI-only, not in-app screens.
How it behaves
The markdown mirror (output only)
Tasks copies the whole tree to one plain markdown file per signed-in account, so other tools and local AI agents can read it without going through the app. The file is output only — the database stays the source of truth, the app never reads the file back, and GET /tasks-v2/markdown renders your tasks from the database, so it always matches what you see.
Each row carries its fields as key= values in a metadata comment above the task text, and every value is escaped so a reader can always split them back out, even when a tag or a note holds a comma, a backslash or something that looks like the comment's own syntax. Due, snooze and start times are written as a wall-clock instant stamped with your own UTC offset, not UTC — honour that offset rather than assuming UTC, or a late-evening deadline reads as the next day.
With Database Encryption on, the mirror is not written at all; use GET /tasks-v2/markdown, which renders from the database. Writes never block a database write: a failure is retried and, if the retries run out, raises the mirror-stale alert. Writes stop while Tasks is off, so turning Tasks off never clobbers a file you already have.
Tasks is still in testing. Turn it on in Settings → Features → Tasks; while it is off, Tasks and its command-line routes do nothing.
Control-server routes (/tasks-v2/*)
Scripts and agents can read and change Tasks through the local control server (127.0.0.1:19519). Every route answers 403 with disabled: true while Tasks is off — deliberately not a 404, so a caller can tell "feature off" from "id not found"; a 404 means only that the id is missing. No key or an invalid one gets 401; a session's own key gets 401 on a write it is not admitted on — the dispatcher's mutation gate turns it away before the handler runs — and 403 on a read it may not make (the trust-class refusal runs before the handler). Neither is the feature-off answer: while Tasks is off, that 403 with disabled: true answers first, before any key is judged.
An agent keeps the account it was started for. A session is bound to the account signed in at launch, and every Tasks route answers it for that account. If the person signs into another account, every Tasks route answers that agent 409 and changes nothing: This agent was started for another account's tasks. Sign in to that account again to let it keep working on them. Signing back in lets it carry on. A full-trust call naming no source session is not held to this.
Which key. Use the full-trust key from ~/.amc/cli-token. A session's own key ($AMC_CLI_TOKEN) is admitted on the agent reads — GET /tasks-v2/list, /task/:id, /:id, /context/list, /lists/list and its deprecated /tasks-v2-lists/list alias, and /markdown — and on the routine single-task writes POST /tasks-v2/create, /update, /complete, /move-to-list, /context/create, /lists/update (a project's name, color, icon or master context, which is how a project agent saves the context it built), /delete, /restore-row-states (only tasks the same session deleted) and /import/parse (202 with an approval request until the user approves that file; /create also admits the Simple Mode concierge's credential). Those are the whole set a Tasks-launched agent needs, so its launch footer points it at $AMC_CLI_TOKEN alone and never at the full-trust file. Every other route refuses it — the shortcut family (GET / PUT / DELETE /tasks-v2/shortcuts…), every other read and every other write need the full-trust key. Deleting many tasks at once, or a whole project, needs the full-trust key: POST /tasks-v2/bulk-delete and the other bulk routes are not on that list, so a session's own key cannot use them. That delete never reaches Ctrl/Cmd+Z history, but the task waits in Recently deleted for 30 days, where the user can restore it; with the full-trust key, GET /tasks-v2/list-deleted lists it and POST /tasks-v2/undelete brings it back. After 30 days it is gone for good. POST /tasks-v2/plan/open and /launch-plate-agent also answer 403 disabled when Plan my day is off, so the error text — not the status code — says which switch to mention.
How fast. Reads allow 60 a minute per key. Writes share 10 a minute across all callers, at most 4 a minute per caller; a request changing many tasks counts as one write. Over either limit a write gets 429 with nothing changed and a Retry-After delay.
| Route | Key / limit | Notes |
|---|---|---|
GET /tasks-v2/list |
full-trust or agent key + reads | ?limit (default 500, cap 2000) and ?cursor page the read; hasMore + nextCursor |
GET /tasks-v2/due-soon |
full-trust key + reads | the Due this week card's own answer: { overdue, today, withinWeek, limit, truncated }, whole task rows by the card's deadline. limit (1–2 000, default 2 000) caps the whole answer, overdue filled first, and truncated: true says rows were left out. Applies the card's rules, not a dueAt window — an AI-inferred-only deadline counts; finished, event, snoozed-future and not-yet-started rows are excluded; the week follows calendarWeekStartDay |
POST /tasks-v2/create |
full-trust, agent or concierge key + writes | 201; 409 if parentId is deleted; text up to 200 characters, optional context saved as a note called "Context". Takes every task field (startAt, estimatedMinutes, metadata for tags and repeat, snoozedUntil, dailyPlateDate, the meeting alarms). With no afterId/beforeId it lands per the add-to-top setting and is auto-capitalized like one typed; position (top/bottom) overrides |
POST /tasks-v2/update |
full-trust or agent key + writes | 404 if id missing; with expectedText, 409 CONFLICT and the current task when the text changed since it was read (nothing written) |
POST /tasks-v2/complete |
full-trust or agent key + writes | 404 if id missing; answers data: {task, spawned, revived, recurrenceStopped}, the same outcome the desktop UI gets |
POST /tasks-v2/delete |
full-trust or session key + writes | soft delete (kept 30 days); idempotent; {deletedCount} |
POST /tasks-v2/restore-row-states |
full-trust or session key + writes | undo by prior row states; a session key can restore only tasks its own session deleted in the last 30 days (403 otherwise) |
GET /tasks-v2/markdown |
full-trust or agent key + reads | text/markdown, no-store, nosniff; renders from the DB, no file read |
GET /tasks-v2/lists/list |
full-trust or agent key + reads | projects + per-project counts + openUnfiledCount (open tasks in no project); ?limit (default 500, cap 2000) + hasMore; pass nextCursor back as ?cursor; a cursor whose project is gone answers 409 CONFLICT |
POST /tasks-v2/lists/create |
full-trust key + writes | 201; returns the new project. Optional afterId places it after that project; omitted or unknown appends. The same X-Client-Request-Id returns the first project |
POST /tasks-v2/lists/update |
full-trust or agent key + writes | 404 if id missing; patches name / color / icon / master context / default project. The same X-Client-Request-Id returns the first save instead of a false conflict |
POST /tasks-v2/lists/delete |
full-trust key + writes | destructive — deletes the project and every task in it (kept 30 days); {deletedListCount, deletedTaskCount}; 404 for an id that never existed; a repeat delete of an already-deleted project still answers with its counts |
POST /tasks-v2/lists/restore |
full-trust key + writes | { id }; undoes the delete; {restoredListCount, restoredTaskCount} |
POST /tasks-v2/bulk-update |
full-trust key + writes | up to 100 IDs; one result per ID, not all-or-nothing. fields takes every update field — including text, dueAt, importance, urgency and snoozedUntil (null wakes a task) — except id, expectedText and metadataBase. Same cross-field rules: a startAt after dueAt, or a plate block ending before it starts, is refused 400; {} is a coded 400 before any ID is touched. Top-level "clampStart": true pulls each row's start back to a new dueAt when it would land after it — the Due this week reschedule-all, and the only way to move a mixed selection in one call; without it those rows are refused |
POST /tasks-v2/bulk-archive |
full-trust key + writes | destructive — archives tasks and their sub-tasks, up to 100 IDs, no confirm prompt |
POST /tasks-v2/bulk-delete |
full-trust key + writes | destructive — deletes tasks and their sub-tasks (kept 30 days), up to 100 IDs, no confirm prompt; one result per ID, and a failed ID never undoes the others |
POST /tasks-v2/bulk-create |
full-trust key + writes | up to 100 tasks; each item takes a single create's fields and the same 200-character text cap, a too-long item failing on its own row. A missing or deleted parent or project on ANY item refuses the whole batch with 409 before anything is written; past that it is not all-or-nothing. Created in the order given within each parent and project. A batch-level afterId/beforeId (not both) places the whole batch; position picks top or bottom. If every item fails on a server refusal it answers 422 with every result under data; a genuine fault answers 503 (database busy) or 500 (unexpected crash), either way carrying every result |
POST /tasks-v2/bulk-move-to-list |
full-trust key + writes | up to 100 IDs; moves tasks to a target project; 404 if project missing |
POST /tasks-v2/unowned-rows/answer |
full-trust key + writes | answers the shared-computer "are these yours?" card headless: { "accountKey", "answer": "claim" | "leave" }, applied at once. 200 { claimed }, or 409 when that question belongs to a different account |
GET /tasks-v2/caught/sources |
full-trust key + reads | each Caught call source's enabled, connected, visible, lastSuccessAt, stagedTotal, lastError and firstRead (the desktop twin is the tasks-v2:call-sources-status channel) |
POST /tasks-v2/overdue/spread |
full-trust key + writes | spreads overdue tasks across the next workdays — the CLI twin of the Due this week card's Spread them out, and the one batch bulk-update cannot express because each task gets its own due date. The screen's plan: most important then oldest due; repeating tasks / events / finished stay put and a task snoozed into the future is not yet overdue; each workday fills to plate size minus what is already due. Answers { dryRun, today, planned, updatedCount, failed }, planned listing every { taskId, dueAt, dueIsDateOnly }, so { "dryRun": true } previews and writes nothing. A task that could not be written lands in failed with its code and error and does not stop the rest; a second call plans nothing because those tasks are no longer overdue. When a call moved nothing, the answer is a refusal rather than a success: 500 INTERNAL (or 503 SERVICE_UNAVAILABLE) when the app itself faulted, 422 UNPROCESSABLE when every task refused the change — the same split the other bulk routes make |
More routes — the paid, the destructive and the outbound ones. These three tables are the rest to treat carefully; plain reads and ordinary writes are in the bundled omniscio-control skill's tasks-v2 reference.
Paid — an approval card comes first. While Require approval: Tasks AI & agent runs is on (the default) each answers 202 with an approval card and spends nothing until the person answers. One spends without a card and says so in its row.
| Route | Key / limit | Notes |
|---|---|---|
POST /tasks-v2/right-now/rerank |
full-trust key + writes, approval card | no body; discards the cached ranking and asks the AI for a fresh one |
POST /tasks-v2/checkin/run |
full-trust key + writes, approval card | no body; opens or generates today's check-in |
POST /tasks-v2/checkin/send |
full-trust key + writes, approval card | { "text" } up to 2 000 characters, trimmed; whitespace-only refused 400 with nothing queued. 409 with nothing queued while a check-in reply is still being written (GET /tasks-v2/checkin says answering: true) |
POST /tasks-v2/interview/run |
full-trust key + writes, approval card | { "taskId", "fresh"? }; 400 without a task id, 404 for an unknown task, nothing queued. Without fresh an already-accepted breakdown is reused (the approval re-opens the old thread and spends nothing); "fresh": true retires it and starts anew, like the panel's Start a new breakdown |
POST /tasks-v2/interview/send |
full-trust key + writes, approval card | { "taskId", "text" }; up to 2 000 characters, trimmed, whitespace-only refused 400. 409 with nothing queued while that task's reply is being written (GET /tasks-v2/interview?taskId=… says answering: true) |
POST /tasks-v2/arrange-ai |
full-trust key + writes, approval card | optional { "plateDate" }; the AI composes the plate order and a per-task rationale |
POST /tasks-v2/plan/open |
full-trust key + writes, approval card | optional { "again": true } re-drafts a plan already committed or still reusable; without it the stored plan comes back as-is. Also 403 disabled while Plan my day is off |
POST /tasks-v2/launch-agent |
full-trust key + writes, approval card | { "taskId", "sessionType"?, "projectId"?, "tier"? }; starts an agent bound to the task. A task that already has a session answers 200 { ok: true, applied: true, result: { status: "reused", sessionId } } and no card. projectId is the repo picker (absent — the hidden Tasks workspace); tier is genius·smart·worker·basic, and an unavailable tier refuses the launch |
POST /tasks-v2/launch-list-agent |
full-trust key + writes, approval card | { "listId", "sessionType"?, "projectId"? }; a project-interview agent for one project. A promptOverride body is refused 400 — custom prompts are app-only. projectId is the repo picker, exactly as on the single-task and batch launches; omit it on any of the three and the launch runs in the project's saved Run agents in code project when that one is still eligible, else the hidden Tasks workspace |
POST /tasks-v2/launch-plate-agent |
full-trust key + writes, approval card | optional { "plateDate" }; the Today Plan-My-Day agent. Also 403 disabled while Plan my day is off |
POST /tasks-v2/launch-macro-session |
full-trust key + writes, approval card | { "macroId" }, one of the presets GET /tasks-v2/macro-sessions lists |
POST /tasks-v2/launch-agent-batch |
full-trust key + writes, approval card | { "taskIds", "sessionType"?, "projectId"? }; ONE agent seeded with the selected tasks, at most 25; a deleted, archived or unknown id is a 404 naming it, no card |
POST /tasks-v2/delegate-start |
full-trust key + writes, approval card | a paid spawn that waits for the approval card like the other paid Tasks AI actions, and sits behind the delegation arming switch as well. Once approved it answers 200 with applied: true and a result.status of started, reused (it joined the task's existing delegation), starting, or awaiting_review when a produced draft is already waiting for review |
POST /tasks-v2/closeout/confirm |
full-trust key + writes | records that a person reviewed the close-out. It spends, with no card: once a day, when Tasks memory is on, it starts the "Learned about you" pass |
Destructive. POST /tasks-v2/bulk-delete, /bulk-archive and /tasks-v2/lists/delete are above; these are the rest. None asks a person first.
| Route | Key / limit | Notes |
|---|---|---|
POST /tasks-v2/archive |
full-trust key + writes | { "id", "markDone"?, "keepRepeating"? }; takes the task and its sub-tasks out of every live list. markDone defaults to false, so a bare { "id" } files it away unfinished. Reversible with /tasks-v2/restore. An id no task has answers 404; a task that is already archived answers 422 |
POST /tasks-v2/archive/undo |
full-trust key + writes | { "id", "spawnedId" }; the one-call undo of a repeating task's FINISH — the inverse of the Finished toast's Undo and Ctrl/Cmd+Z. spawnedId is the spawned.id the finish answered with. It removes that next occurrence, reopens the finished task (reverting archived_at / done / repeat-stamp) and answers { restoredCount, restoredIds, updatedAt, removedSuccessorId } (removedSuccessorId is null if it was already gone). 422 with nothing changed for a task not archived or an id that is not that next occurrence; if it was already removed and the reopen changes nothing it is put back (successorPutBack: true). For a non-repeating task use /tasks-v2/restore |
POST /tasks-v2/context/delete |
full-trust key + writes | { "id" }; soft-deletes one context item of a task; 404 for an id that never existed, deletedCount: 0 for one already deleted |
POST /tasks-v2/attachments/delete |
full-trust key + writes | { "id" }; removes one attached file; 404 for an id that never existed, deletedCount: 0 for one already removed. Reversible with /tasks-v2/attachments/restore |
POST /tasks-v2/caught/dismiss |
full-trust key + writes | { "id", "reason"? }; throws away one caught suggestion. reason: "not-a-task" also teaches later session and email scans to stop suggesting that kind while Tasks memory is on (with memory off, only a meeting action item with the exact same text is skipped). Reversible with /tasks-v2/caught/undo-dismiss |
POST /tasks-v2/caught/dismiss-all |
full-trust key + writes | no body; throws away every pending caught suggestion at once |
POST /tasks-v2/learnings/:id/dismiss |
full-trust key + writes | throws away one "Learned about you" row; 404 for an id that never existed, success for one already dismissed |
POST /tasks-v2/learnings/reset |
full-trust key + approval | wipes every AI-learned row with the day log and the distill markers; rows a person edited are kept. It erases permanently, so it waits for your approval card first and nothing happens until you tap Approve |
POST /tasks-v2/ai-conversations/clear |
full-trust key + approval | no body; deletes every check-in and breakdown-interview conversation of the signed-in account. Like the reset above, it erases permanently and waits for your approval card first |
POST /tasks-v2/import/undo |
full-trust key + writes | { "runId" }; removes the tasks one finished import run created |
Outbound — these leave the computer. Each fetches from the address you name; treat the URL as the argument it is.
| Route | Key / limit | Notes |
|---|---|---|
POST /tasks-v2/fetch-link-title |
full-trust key + writes | { "url" }; fetches the page and returns its title as a [title](url) markdown link, title: null when none |
POST /tasks-v2/fetch-video-title |
full-trust key + writes | { "url", "provider" } with provider youtube or vimeo; resolves the title through that provider's own oEmbed endpoint, title: null on a miss |
POST /tasks-v2/context/refresh |
full-trust key + writes | { "id" }; re-fetches a ContextDock item from its source. 422 when the item is not a ContextDock item or ContextDock is off, 503 (or 408 on a timeout) with a CONTEXTDOCK_<CAUSE> reason when the ContextDock fetch fails, and 502 only for a non-ContextDock network error |
Import. /tasks-v2/import/undo is a destructive route above; these three are the rest of the import path. parse is the only one a session key can reach, and only after the owner approves the file it names.
| Route | Key / limit | Notes |
|---|---|---|
POST /tasks-v2/import/parse |
full-trust key, or a session key with the owner's approval | { "filePath" }, an absolute path on this computer; a network-share or device path is refused. Returns the file's headers, rows and suggested column mappings. From a session the answer is 202 APPROVAL_REQUIRED with an inbox card naming that file and nothing read; a decline answers 403 and is not raised again |
POST /tasks-v2/import/preview |
full-trust key + writes | { "rows", "headers", "mappings", "targetListId"?, "skipDuplicates"? }; says what an import would create without creating it. The body may be as large as a file at the 10 MB parse cap, since these are the rows parse handed back |
POST /tasks-v2/import/execute |
full-trust key + writes | the same body and the same size allowance; creates the tasks and answers runId, createdCount, skippedCount, createdListIds, droppedFields and per-row errors. 201 when it created tasks (with partial: true when only some rows went in), 200 when nothing was created and nothing failed (every row a duplicate), 422 when no row could be imported. A retry carrying the same X-Client-Request-Id and body replays the first run's answer with idempotent: true instead of importing again; a call with no request id is remembered by its body for the same window, so an identical body sent again answers the first run rather than importing every row a second time — send a new X-Client-Request-Id (or change the body) when a second import of the same rows is genuinely wanted |
Privacy — the "Share with agent" flag. Whether a file attached to a task is disclosed to an agent launched on that task is a per-file flag, off by default; one route flips it.
| Route | Key / limit | Notes |
|---|---|---|
POST /tasks-v2/attachments/set-share |
full-trust key + writes | { "id", "shareWithAgent" }; sets the same checkbox the task's Attachments section shows, so true discloses that file to an agent launched on the task and false withholds it. 404 (NOT_FOUND) when the attachment no longer exists. A session key cannot call it |
Page size. Every tasks-v2 list read — GET /tasks-v2/list, /tasks-v2/list-archived, /tasks-v2/context/list and /tasks-v2/lists/list — takes ?limit through one reader: default 500, ceiling 2 000, and a limit past the ceiling (or not a whole number from 1) is refused with a coded 400 VALIDATION_FAILED rather than clamped. /tasks-v2/list-archived and /tasks-v2/list-deleted also take ?cursor and answer nextCursor; a cursor whose anchor row is gone answers a coded 409 CONFLICT telling the caller to re-request without one, the one status every stale cursor answers. Over IPC the renderer may ask up to 10 000 (it renders the whole tree in-process); the CLI stops at 2 000 because every row is serialized over HTTP.
Booleans in a query. includeDone, includeSnoozed and includeArchived accept only true, false, 1 and 0. An empty value counts as absent; any other non-empty token (TRUE, yes, 1) is refused with a coded 400 naming the field.
Searching the list. ?query= on GET /tasks-v2/list returns only tasks whose text matches, ignoring accents and capitals; a % or _ is matched literally, not as a wildcard. The search runs before paging, so limit and cursor page through the matches. A task also matches when one of its tags (metadata.tags) contains the query, folded the same way; a non-list tags value, or a non-text tag, is ignored.
POST /tasks-v2/drip-now treats a release that reached no inbox as a failure. It applies the in-app Send-to-inbox rule: success only when at least one alert landed. Held back by the user's inbox settings answers 422; every alert write failing to confirm answers 503 (SERVICE_UNAVAILABLE). Each reply carries releasedCount, notShown and unconfirmed, distinguishing "the user's rules held the alerts back" from "the alert store is broken".
Extra limits and aliases. Over a write limit, the 429 names which of the two ran out. POST /tasks-v2/delegate-start also caps at 2 a minute (429 with retryAfterSeconds and Retry-After), and the daily launch cap names the wait until local midnight. When the agent cannot be started: 403 on an unverified copy of the app, 404 or 503 when the Tasks workspace is missing or not ready. The /tasks-v2/lists/* paths are the canonical form of the list routes; the older /tasks-v2-lists/* paths are served by the same handlers but are deprecated and answer Deprecation: true with a Link header naming the successor. The same holds for delegation: /tasks-v2/delegation/<verb> is canonical, and the flat /tasks-v2/delegate-* names are its deprecated aliases, answering identically plus Deprecation: true and a successor Link.
Both create doors warn an agent first. Tasks is the person's own personal to-do list, so an agent's work never belongs there; it goes to the agent task system (the agent-tasks skill). The first POST /tasks-v2/create or /tasks-v2/bulk-create from the full-trust key, an agent or cloud session key, or an MCP capability answers 409 with reason: "personal-list-warning" and writes nothing. Sending the exact same request again from the same session within 10 minutes adds it; a third identical send is warned again. The Ask and Simple Mode helper key and API keys are not warned, and the person's own screens never meet it. AMC_DISABLE_PERSONAL_LIST_WARNING=1 on the app turns it off.
Both create doors hold the same short-title rule. A CLI-filed task line is capped at 200 characters, whether one task or a hundred.
POST /tasks-v2/createadds CLI guardrails to the shared schema:textcapped at 200 characters, detail in an optionalcontext(up to 50,000 characters) saved as a note labeled "Context". Over the cap it answers a coded 400 telling you to shortentextand move detail intocontext. Omittingcontextis allowed — the answer carries aguidanceline. If the task is created but the note cannot be attached, the answer carries awarning. The cap is CLI-only; a desktop or IPC create is not held to it.POST /tasks-v2/bulk-createapplies the same cap to every item; a too-long item is its ownok: falserow withcode: "VALIDATION_FAILED"and the same guidance, and the rest of the batch still creates. Its items have nocontextfield (sending one is a 400), so long-form detail belongs on a single create.
So a 400-character task line is refused by both doors: send detail through context on a single create, or split the work.
Bulk text. bulk-update holds each task's text to the same 200-character CLI cap as a single edit — over it, the whole call is refused with a coded 400 VALIDATION_FAILED before any ID is touched. bulk-create applies that same cap item by item, while its stored text keeps the 10,000-character bound.
Bulk-create order. Tasks are stored in the order sent: items for the same project (and parent) are created one after another, so an imported checklist keeps its numbering; items for different projects are created in parallel.
Bulk dates. A task can't start after it is due, and bulk-create holds every item to it: an item whose startAt is later than its dueAt is refused with a 400 naming it, with nothing in the batch written. The rule also covers a dueAt the item never sent — a repeat rule fills the due from the schedule, and if that lands before startAt the item is its own ok: false row with code: "VALIDATION_FAILED" while the rest is created.
Bulk answers. Update, archive, delete and move answer one result per ID, each failure carrying a code:
NOT_FOUND— the task does not exist; drop that ID.UNPROCESSABLE— it changed nothing, for example because it was already archived.- A domain refusal such as
CONFLICTkeeps its own code. INTERNAL— a server fault; retry that ID.
Update, archive and delete work eight at a time (not in the order sent); move works one at a time, in order. Read results and resend only the failed IDs — never resume from a remembered position. Bulk-create answers one result per item, keyed by its index in tasks.
When no ID changed, the answer is 422 with a top-level error and code: "UNPROCESSABLE" beside the results. When no ID changed and at least one hit a server fault, the answer is 500 INTERNAL (or 503 SERVICE_UNAVAILABLE when the database was busy) with a ref, still carrying the same data.results, so you can retry those IDs. A batch where some IDs worked answers 200. Repeating a bulk-delete of already-deleted tasks counts them as done and answers 200.
A complete or archive reply names why a repeat stopped in recurrenceStopped: no-due, no-next-occurrence or invalid-rule, kebab-case like the other multi-word values on these routes.
Archive, delete and move accept X-Client-Request-Id; a retry with the same ID returns the first answer marked idempotent: true, and bulk-create marks its replays the same way. Bulk-delete needs the full-trust key although single delete also takes an agent's key. Each single delete goes through the per-call write limit; one bulk-delete reaches up to 100 tasks.
Retrying a write safely. Send a stable X-Client-Request-Id on every write and reuse it on a retry. Not every write replays by it: the routes described below answer a repeat with the first answer marked idempotent: true, and the rest re-run the request — most land on the same state because they write fixed values, but the repeat is not marked idempotent. TASKS_V2_ROUTE_REPLAY in src/main/services/cli/tasks-v2/route-registrar.ts declares, for every write, whether it replays a request id (header), is safe to repeat only because it lands on the same state (state-idempotent), or is neither (none).
POST /tasks-v2/createand/context/createalso accept it asclientRequestIdin the body (the header wins)./from-session,/duplicate,/indent,/tasks-v2/lists/create//updateand the delegation settle routes (/delegate-accept//delegate-reject, and their/delegation/accept//delegation/rejectspellings) replay a repeated header id. Accepting a draft files it as a context note, so without an id a second accept still answers409— the request id is what turns a lost reply into the first answer instead of a false failure. Two identical requests at the same moment with no id run once.GET /tasks-v2/delegate-listand/delegate-list-activeanswer at most 200 rows and page no further: there is nolimitor cursor. Both answerdata.hasMore, which istruewhen the 200-row cap hid older rows, so check it before treating the rows returned as the whole history./bulk-createwith no id remembers a finished batch for 10 minutes: the same caller re-sending the identical batch gets the first answer, so a retry after a timeout never creates (or announces) the tasks twice. A different caller or a changed batch creates as usual.- Paid AI routes (
/checkin/send,/interview/send,/arrange-aiand the rest) with no id keep the first request's key while it runs and 30 seconds after it succeeds, so a retry joins or replays the first turn instead of paying twice.
POST /tasks-v2/reorder and /tasks-v2/lists/reorder are available too. The Break it down interview is here as well (GET /tasks-v2/interview, POST /tasks-v2/interview/accept / /run / /send); running and sending spend AI tokens, so while Require approval: Tasks AI & agent runs is on (the default) those steps wait for approval.
Setting a time on a task (dueAt, snoozedUntil, startAt, waitingSince, followUpAt)
Send the plain local time. Do not convert to UTC yourself. POST /tasks-v2/create and /update (and the bulk routes) accept three shapes, storing each as one exact moment (US Eastern summer examples):
| You send | Read as | Stored |
|---|---|---|
2026-08-18T15:00 |
3 PM in the user's own time zone ← prefer this | 2026-08-18T19:00:00.000Z |
2026-08-18T15:00:00-04:00 |
the offset you stated | 2026-08-18T19:00:00.000Z |
2026-08-18T15:00:00.000Z |
a genuine UTC instant | 2026-08-18T15:00:00.000Z |
The zoneless form is the one to reach for — the only shape that cannot be got wrong. Omniscio reads it in the desktop computer's time zone, so it survives daylight-saving changes (after a time-zone change, once restarted).
Never add Z to a local time you have not actually converted. A Z says "this is already UTC", so nothing can catch the mistake and the reminder fires at the wrong hour: a 3 PM Eastern deadline sent as 2026-08-18T15:00:00.000Z reminded its owner at 11 AM.
A bare date (2026-08-18), a bare clock (15:00) and words like tomorrow are rejected — these fields take a date and time, never a phrase. A client in a different time zone from the desktop app should send the explicit-offset form, because a zoneless time is always read in the desktop's zone.
Agents and scripts can delete tasks without asking
The Require approval: Tasks AI & agent runs setting covers the paid Tasks AI actions, and starting an AI delegation run on a task is one of them: it waits for the approval card first (on by default whenever Tasks is on). One paid action is not covered: confirming the evening close-out, which starts the once-a-day "Learned about you" pass when Tasks memory is on. That one does not ask first. When an agent or script deletes, archives or moves tasks through the local control server, Omniscio does not ask first — the change happens right away:
- One request can delete or archive up to 100 tasks, with their sub-tasks.
- One request can delete a whole project and every task in it.
- An agent can delete a single task with its own session key; many at once, or a whole project, needs the full-trust key.
- A request for many tasks is not all-or-nothing; tasks already deleted or archived stay that way.
A deleted task is kept 30 days, and you can bring one back — including one an agent deleted — from Recently deleted in the Tasks ⋯ More menu (see Archive & universal undo). Archived tasks stay in Archived, where you can restore them.
Related
The overview, the other parts, and everything else worth reading next all sit on Tasks (markdown outliner, in development). The Free plan's 100-task limit, its "You've reached the free task limit" pop-up and the Clean up panel are on The Free plan's task limit.
Last verified 2026-10-30