Omniscio

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/create adds CLI guardrails to the shared schema: text capped at 200 characters, detail in an optional context (up to 50,000 characters) saved as a note labeled "Context". Over the cap it answers a coded 400 telling you to shorten text and move detail into context. Omitting context is allowed — the answer carries a guidance line. If the task is created but the note cannot be attached, the answer carries a warning. The cap is CLI-only; a desktop or IPC create is not held to it.
  • POST /tasks-v2/bulk-create applies the same cap to every item; a too-long item is its own ok: false row with code: "VALIDATION_FAILED" and the same guidance, and the rest of the batch still creates. Its items have no context field (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 CONFLICT keeps 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/create and /context/create also accept it as clientRequestId in the body (the header wins).
  • /from-session, /duplicate, /indent, /tasks-v2/lists/create / /update and the delegation settle routes (/delegate-accept / /delegate-reject, and their /delegation/accept / /delegation/reject spellings) replay a repeated header id. Accepting a draft files it as a context note, so without an id a second accept still answers 409 — 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-list and /delegate-list-active answer at most 200 rows and page no further: there is no limit or cursor. Both answer data.hasMore, which is true when the 200-row cap hid older rows, so check it before treating the rows returned as the whole history.
  • /bulk-create with 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-ai and 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.

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