TODO for AI API

todo

Endpoint

Todo list

GET

https://api.todofor.ai/api/v1

/projects/{projectId}/todos

Returns a page of todos in a project (lightweight, newest-activity-first). Use cursor (lastActivityAt of the last item) to fetch older pages; search filters by content/status, agentSettingsId/businessContextId filter by agent/business context.

Todo list › path Parameters

projectIdstring · required

Todo list › Responses

Successful response

itemsobject[] · required

nextCursornumber
lastActivityAt of the last item; pass as cursor for the next page. Absent = last page.

Todo listOrchestrators

GET

https://api.todofor.ai/api/v1

/projects/{projectId}/orchestrators

Orchestrator threads of a project, newest first (hidden from the board list).

Todo listOrchestrators › path Parameters

projectIdstring · required

Todo listOrchestrators › Responses

Successful response

itemsobject[] · required

nextCursornumber
lastActivityAt of the last item; pass as cursor for the next page. Absent = last page.

Todo get

GET

https://api.todofor.ai/api/v1

/todos/{todoId}

Retrieves a complete todo item including all messages, blocks, and metadata. Pass messageLimit to include only the newest N messages (hasMoreMessages signals older ones — page them via /todos/{todoId}/messages). Requires read access to the todo (either as owner or through project sharing).

Todo get › path Parameters

todoIdstring · required

Todo get › Responses

Successful response

idstring · required
projectIdstring · required
statusrequired
agentSettingsIdstring · required
contentstring · required
messageIdsstring[] · required
messagesobject[] · required
createdAtnumber · required
lastActivityAtnumber · required
scheduledTimestampnumber · required
0 if immediate

groupTagstring
Project-scoped group slug.
privateOwnerIdstring
Set (server-side, from the creator) when the todo lives in MY_PRIVATE_GROUP: only this user may read or modify it. Never accepted from clients.
parentTodoIdstring
Todo whose agent shell spawned this one (via tfa-cli).
kind
'orchestrator': a per-tab orchestrator thread — the tab runs the agent loop itself and authors the assistant turns over the frontend socket. Always created with visible:false (off the board); listed via todo.listOrchestrators.
systemMessageIdstring
checkedBlockIdsstring[]
User-checked blocks
actionableBlockIdsstring[]
Blocks with code, commands, etc.
archivedAtnumber
deletedAtnumber
dismissedAtnumber
When the proposal was dismissed — bounds the analyzer's feedback window.
starredAtnumber
Star/favorite timestamp; absent/0 = not starred
contributorIdsstring[]
Users who sent messages into the todo, in order of first appearance ([0] = creator).
workflowVersionstring
For optimistic concurrency
visibleboolean
Visible in default project listings; defaults to true.
isPublicboolean
Publicly viewable (read-only) by anyone with the link, no login required.
commentsEnabledboolean
Signed-in non-members may comment on a public todo. Members can always comment.
autoDoneboolean
Pre-finished: the user checked it while the agent was still working, so the run's READY lands as DONE. Cleared once the todo reaches a terminal status.
statusRevnumber
Per-todo transition counter at status — travels WITH it, so a client knows which transition it holds.
hasMoreMessagesboolean
True when messages holds only the newest page — older ones via todo.getMessages.
importSourceobject
Provenance of an imported todo (see ImportSessionInput.source).

Todo update

PUT

https://api.todofor.ai/api/v1

/todos/{todoId}

Updates todo properties like content, scheduled time, or assigned agent. Requires write access to the todo.

Todo update › path Parameters

todoIdstring · required

Todo update › Request Body

todoIdstring · required
The unique identifier of the todo to update

contentstring
New content/prompt for the todo
scheduledTimestampnumber
Unix timestamp to schedule the todo (0 or omit for immediate)
agentSettingsIdstring
ID of the agent settings to use for processing
groupTagstring
Group slug. Pass an empty string to make the todo ungrouped.
starredAtnumber
Star/favorite timestamp; pass a timestamp to star, 0 to unstar
isPublicboolean
Make the todo publicly viewable (read-only) by anyone with the link
commentsEnabledboolean
Let signed-in non-members comment on the public todo
autoDoneboolean
Pre-finish a running todo: its READY will land as DONE. false cancels.

Todo update › Responses

Successful response

null

Todo delete

DELETE

https://api.todofor.ai/api/v1

/todos/{todoId}

Moves a todo to the trash (status DELETED). It leaves every list and count but keeps its messages; undo with restore. Requires write access to the todo.

Todo delete › path Parameters

todoIdstring · required

Todo delete › Request Body

todoIdstring · required
The unique identifier of the todo item.

Todo delete › Responses

Successful response

null

Todo searchMessages

GET

https://api.todofor.ai/api/v1

/messages/search

Search message content across all accessible projects. mode: lexical (all words, newest first — default), semantic (KNN), fused (any word BM25 ∪ KNN, rank-fused — best recall). Optionally scope by projectId, todoId, role; exclude drops already-read message ids.

Todo searchMessages › Responses

Successful response

hitsobject[] · required
totalnumber · required
Total matches (may exceed hits.length). Fused: the lexical count.

lexicalCountnumber
Fused mode: how many messages contain at least one query word (index count, before exclude). Tells the reader whether a set is larger than the page.

Todo searchUnified

GET

https://api.todofor.ai/api/v1

/search

Global conversations and memory search, using the same semantic search service as tfa-memory.

Todo searchUnified › Responses

Successful response

hitsobject[] · required

todosobject[]
Project-scoped board rows for the displayed visible TODOs, without messages.
warningsstring[]
Partial-search warnings returned by memory-manager.

Todo listChildren

GET

https://api.todofor.ai/api/v1

/todos/{todoId}/children

Todos spawned by this todo (an orchestrator thread's children), newest activity first.

Todo listChildren › path Parameters

todoIdstring · required

Todo listChildren › Responses

Successful response

itemsobject[] · required

nextCursornumber
lastActivityAt of the last item; pass as cursor for the next page. Absent = last page.

Todo getMessages

GET

https://api.todofor.ai/api/v1

/todos/{todoId}/messages

Returns a page of messages in chat order. Omit before for the newest page; pass the oldest loaded messageId as before to fetch older ones.

Todo getMessages › path Parameters

todoIdstring · required

Todo getMessages › Responses

Successful response

messagesobject[] · required
hasMoreboolean · required
True if older messages exist before this page.

Todo addMessage

POST

https://api.todofor.ai/api/v1

/todos/{todoId}/messages

Adds a new user message to the todo conversation. This can optionally trigger the AI agent to start processing immediately or schedule it for later.

Todo addMessage › path Parameters

todoIdstring · required

Todo addMessage › Request Body

todoIdstring · required
projectIdstring · required
contentstring · required
agentSettingsobject · required
AI AgentSettings configuration including model, system prompt, and MCP tools.

attachmentsobject[]
Attachments metadata (content arrives separately via binary WebSocket frames or current attachments buffer).
scheduledTimestampnumber
afterMessageIdstring
autoDoneboolean
When true, the next successful agent completion lands in DONE (strikethrough) instead of READY. Per-run flag — does not persist on the todo.
origin
Orchestrator threads: how this turn was produced.

Todo addMessage › Responses

Successful response

idstring · required
todoIdstring · required
contentstring · required
rolestring · required
'user', 'assistant', or 'system'
agentSettingsIdstring · required
stop_sequencestring · required
Stop sequence that ended AI response, if any
createdAtnumber · required
blocksarray · required
Parsed content blocks (code, tool calls, text)
scheduledTimestampnumber · required
0 if sent immediately
attachmentsobject[] · required

origin
projectIdstring
Project the todo belongs to (denormalized for search; absent on legacy messages).
userIdstring
Who this turn belongs to: the submitter for a user message, the submitter of the turn being answered for an assistant/tool message. Together with agentSettingsId this is the run's identity — continuations (flushToolMessage) MUST resolve from here, never from todo.agentSettingsId, which is last-writer-wins and gets overwritten when a second user joins the todo. Absent on legacy messages (pre multi-user attribution) — callers fall back to the project owner.
queuedboolean
Sent into an already-running turn, so it sits in the agent's internal queue until the turn drains it. While true the user can still retract it (Front2Agent.TODO_QUEUE_CANCEL); cleared on Agent2Server.TODO_MSG_DEQUEUED.
runMetaobject[]
Token usage, model info, etc.
systemPromptstring
System prompt used for this assistant message (dev mode / debug-dump turns)
toolSchemasstring
Debug-dump turns (x-tfa-debug): native tool schemas of the LLM request that produced this assistant message, JSON-stringified.
predictedReplystring
Predicted next user message (ghost text), computed once per finished assistant turn by reusing the warm prompt cache. Set only on assistant messages; throwaway, never fed back.
parentBlockIdstring
If set, this message belongs to a sub-agent spawned by the given block

Todo getMessagesAround

GET

https://api.todofor.ai/api/v1

/todos/{todoId}/messages/around

Chat-order window around one message: before older messages, the message itself, after newer ones. A large after reads the rest of the todo.

Todo getMessagesAround › path Parameters

todoIdstring · required

Todo getMessagesAround › Responses

Successful response

messagesobject[] · required
indexnumber · required
Position of the pivot in the todo (0-based) and the todo's message count.
totalnumber · required

Todo reportAiOutput

POST

https://api.todofor.ai/api/v1

/report-ai-output

Reports offensive or unsafe AI-generated output to the developer for review.

Todo reportAiOutput › Request Body

detailsstring · maxLength: 2000 · required

todoIdstring
messageIdstring

Todo reportAiOutput › Responses

Successful response

successboolean · required

Todo getPublic

GET

https://api.todofor.ai/api/v1

/public/todos/{todoId}

Retrieves a publicly-shared todo (read-only) including its messages. No authentication required; only returns the todo if it has been made public.

Todo getPublic › path Parameters

todoIdstring · required

Todo getPublic › Responses

Successful response

idstring · required
projectIdstring · required
statusrequired
agentSettingsIdstring · required
contentstring · required
messageIdsstring[] · required
messagesobject[] · required
createdAtnumber · required
lastActivityAtnumber · required
scheduledTimestampnumber · required
0 if immediate

groupTagstring
Project-scoped group slug.
privateOwnerIdstring
Set (server-side, from the creator) when the todo lives in MY_PRIVATE_GROUP: only this user may read or modify it. Never accepted from clients.
parentTodoIdstring
Todo whose agent shell spawned this one (via tfa-cli).
kind
'orchestrator': a per-tab orchestrator thread — the tab runs the agent loop itself and authors the assistant turns over the frontend socket. Always created with visible:false (off the board); listed via todo.listOrchestrators.
systemMessageIdstring
checkedBlockIdsstring[]
User-checked blocks
actionableBlockIdsstring[]
Blocks with code, commands, etc.
archivedAtnumber
deletedAtnumber
dismissedAtnumber
When the proposal was dismissed — bounds the analyzer's feedback window.
starredAtnumber
Star/favorite timestamp; absent/0 = not starred
contributorIdsstring[]
Users who sent messages into the todo, in order of first appearance ([0] = creator).
workflowVersionstring
For optimistic concurrency
visibleboolean
Visible in default project listings; defaults to true.
isPublicboolean
Publicly viewable (read-only) by anyone with the link, no login required.
commentsEnabledboolean
Signed-in non-members may comment on a public todo. Members can always comment.
autoDoneboolean
Pre-finished: the user checked it while the agent was still working, so the run's READY lands as DONE. Cleared once the todo reaches a terminal status.
statusRevnumber
Per-todo transition counter at status — travels WITH it, so a client knows which transition it holds.
hasMoreMessagesboolean
True when messages holds only the newest page — older ones via todo.getMessages.
importSourceobject
Provenance of an imported todo (see ImportSessionInput.source).

Todo getPublicMeta

GET

https://api.todofor.ai/api/v1

/public/todos/{todoId}/meta

Lightweight social-preview data (title, contributors, file stats) for a publicly-shared todo. No authentication required.

Todo getPublicMeta › path Parameters

todoIdstring · required

Todo getPublicMeta › Responses

Successful response

idstring · required
titlestring · required
createdAtnumber · required
lastActivityAtnumber · required
messageCountnumber · required
subagentCountnumber · required
Todos spawned from this one (parentTodoId === id).
contributorsobject[] · required
Message senders in order of first appearance ([0] = creator).

projectNamestring
Only set when the parent project is itself public (private project names stay private).
agentNamestring
fileChangesobject
Files touched by file tools / shell file tracking, deduped by path. Absent when none.

Todo updateStatus

PATCH

https://api.todofor.ai/api/v1

/todos/{todoId}/status

Changes the status of a todo (e.g., pause, resume, complete, cancel). Use this to control the execution state of a running AI task.

Todo updateStatus › path Parameters

todoIdstring · required

Todo updateStatus › Request Body

todoIdstring · required
The unique identifier of the todo to update
statusrequired

Todo updateStatus › Responses

Successful response

null

Todo restore

POST

https://api.todofor.ai/api/v1

/todos/{todoId}/restore

Brings a trashed (DELETED) todo back to the status it had before deletion. No-op if it is not deleted.

Todo restore › path Parameters

todoIdstring · required

Todo restore › Request Body

todoIdstring · required
The unique identifier of the todo item.

Todo restore › Responses

Successful response

null

Todo importSession

POST

https://api.todofor.ai/api/v1

/todos/import

Imports an external agent session (Claude Code / Codex) as a finished todo with its message history. No agent run. Idempotent per source path: same sha256 is a no-op, newer content replaces the imported messages.

Todo importSession › Request Body

projectIdstring · required
agentSettingsIdstring · required
titlestring · required
Todo title.
messagesobject[] · required
sourceobject · required

Todo importSession › Responses

Successful response

todoIdstring · required
outcomerequired
created = first import; updated = changed content, re-imported as a new todo; unchanged = same sha256.
messageCountnumber · required

Todo updateMessage

PATCH

https://api.todofor.ai/api/v1

/todos/{todoId}/messages/{messageId}

Updates a scheduled message before it starts processing.

Todo updateMessage › path Parameters

todoIdstring · required
messageIdstring · required

Todo updateMessage › Request Body

todoIdstring · required
messageIdstring · required
agentSettingsIdstring · required

contentstring
attachmentsobject[]
scheduledTimestampnumber

Todo updateMessage › Responses

Successful response

null

Todo updateAndStart

POST

https://api.todofor.ai/api/v1

/todos/{todoId}/update-start

Updates a message and immediately starts AI processing.

Todo updateAndStart › path Parameters

todoIdstring · required

Todo updateAndStart › Request Body

todoIdstring · required
agentSettingsobject · required
AI AgentSettings configuration including model, system prompt, and MCP tools.

messageIdstring
The message to update and run. Omit for an unstarted draft — the server then starts the todo's own first (and only) message, so callers that just want "press Start" don't have to fetch it first. Required when targeting a specific turn (e.g. a scheduled message).
contentstring
attachmentsobject[]
autoDoneboolean
When true, the next successful agent completion lands in DONE (strikethrough) instead of READY. Per-run flag — does not persist on the todo.

Todo updateAndStart › Responses

Successful response

null

Todo linkBlockSubTodo

POST

https://api.todofor.ai/api/v1

/todos/{todoId}/blocks/{blockId}/subtodo

Links a spawned sub-agent todo to the block that launched it (appends to subTodoIds, deduplicated), so the UI nests the sub-agent's live run inside that block. One command may link several runs. Used by the tfa-* CLIs.

Todo linkBlockSubTodo › path Parameters

todoIdstring · required
blockIdstring · required

Todo linkBlockSubTodo › Request Body

todoIdstring · required
messageIdstring · required
blockIdstring · required
subTodoIdstring · required
Todo id of the sub-agent run to nest inside the block.

Todo linkBlockSubTodo › Responses

Successful response

null

Todo clearBlockResult

POST

https://api.todofor.ai/api/v1

/todos/{todoId}/messages/{messageId}/blocks/{blockId}/clear-result

Clears a tool block's result and result attachments, replacing them with a placeholder. Escape hatch for oversized/corrupt results that break subsequent LLM calls.

Todo clearBlockResult › path Parameters

todoIdstring · required
messageIdstring · required
blockIdstring · required

Todo clearBlockResult › Request Body

todoIdstring · required
messageIdstring · required
blockIdstring · required

Todo clearBlockResult › Responses

Successful response

null

Todo toggleBlockChecked

POST

https://api.todofor.ai/api/v1

/todos/{todoId}/blocks/{blockId}/checked

Toggles the checked/completed state of an actionable block.

Todo toggleBlockChecked › path Parameters

todoIdstring · required
blockIdstring · required

Todo toggleBlockChecked › Request Body

todoIdstring · required
blockIdstring · required

Todo toggleBlockChecked › Responses

Successful response

null

Todo updateAgentMapping

POST

https://api.todofor.ai/api/v1

/todos/{todoId}/todo-agent-mapping

Updates which AI agent settings to use for this todo.

Todo updateAgentMapping › path Parameters

todoIdstring · required

Todo updateAgentMapping › Request Body

todoIdstring · required
agentSettingsIdstring · required

Todo updateAgentMapping › Responses

Successful response

null

POST

https://api.todofor.ai/api/v1

/todos/{todoId}/subscribe

Subscribes to real-time updates for a todo via WebSocket and returns the full todo with messages. This atomic operation ensures the cache is populated before any WebSocket messages can arrive, eliminating race conditions.

todoIdstring · required

todoIdstring · required
The unique identifier of the todo item.

Successful response

idstring · required
projectIdstring · required
statusrequired
agentSettingsIdstring · required
contentstring · required
messageIdsstring[] · required
messagesobject[] · required
createdAtnumber · required
lastActivityAtnumber · required
scheduledTimestampnumber · required
0 if immediate

groupTagstring
Project-scoped group slug.
privateOwnerIdstring
Set (server-side, from the creator) when the todo lives in MY_PRIVATE_GROUP: only this user may read or modify it. Never accepted from clients.
parentTodoIdstring
Todo whose agent shell spawned this one (via tfa-cli).
kind
'orchestrator': a per-tab orchestrator thread — the tab runs the agent loop itself and authors the assistant turns over the frontend socket. Always created with visible:false (off the board); listed via todo.listOrchestrators.
systemMessageIdstring
checkedBlockIdsstring[]
User-checked blocks
actionableBlockIdsstring[]
Blocks with code, commands, etc.
archivedAtnumber
deletedAtnumber
dismissedAtnumber
When the proposal was dismissed — bounds the analyzer's feedback window.
starredAtnumber
Star/favorite timestamp; absent/0 = not starred
contributorIdsstring[]
Users who sent messages into the todo, in order of first appearance ([0] = creator).
workflowVersionstring
For optimistic concurrency
visibleboolean
Visible in default project listings; defaults to true.
isPublicboolean
Publicly viewable (read-only) by anyone with the link, no login required.
commentsEnabledboolean
Signed-in non-members may comment on a public todo. Members can always comment.
autoDoneboolean
Pre-finished: the user checked it while the agent was still working, so the run's READY lands as DONE. Cleared once the todo reaches a terminal status.
statusRevnumber
Per-todo transition counter at status — travels WITH it, so a client knows which transition it holds.
hasMoreMessagesboolean
True when messages holds only the newest page — older ones via todo.getMessages.
importSourceobject
Provenance of an imported todo (see ImportSessionInput.source).

Todo getWorkflow

GET

https://api.todofor.ai/api/v1

/todos/{todoId}/workflow

Returns the internal workflow state for debugging.

Todo getWorkflow › path Parameters

todoIdstring · required

Todo getWorkflow › Responses

Successful response

workflowMetarequired
workflowVersionrequired

lastContextSummary
The most recent context summary (if any compaction occurred)

Todo updateWorkflow

PUT

https://api.todofor.ai/api/v1

/todos/{todoId}/workflow

Directly updates the internal workflow state. Set contextSummaryUsed=true to mark pending context summary as used.

Todo updateWorkflow › path Parameters

todoIdstring · required

Todo updateWorkflow › Request Body

todoIdstring · required
workflowMetastring · required
workflowVersionstring · required

contextSummaryUsedboolean
Set to true to mark the pending context summary as 'used'

Todo updateWorkflow › Responses

Successful response

null

task todoRegistry

todo

Todo list

Todo list › path Parameters

Todo list › Responses

Todo listOrchestrators

Todo listOrchestrators › path Parameters

Todo listOrchestrators › Responses

Todo get

Todo get › path Parameters

Todo get › Responses

Todo update

Todo update › path Parameters

Todo update › Request Body

Todo update › Responses

Todo delete

Todo delete › path Parameters

Todo delete › Request Body

Todo delete › Responses

Todo searchMessages

Todo searchMessages › Responses

Todo searchUnified

Todo searchUnified › Responses

Todo listChildren

Todo listChildren › path Parameters

Todo listChildren › Responses

Todo getMessages

Todo getMessages › path Parameters

Todo getMessages › Responses

Todo addMessage

Todo addMessage › path Parameters

Todo addMessage › Request Body

Todo addMessage › Responses

Todo getMessagesAround

Todo getMessagesAround › path Parameters

Todo getMessagesAround › Responses

Todo reportAiOutput

Todo reportAiOutput › Request Body

Todo reportAiOutput › Responses

Todo getPublic

Todo getPublic › path Parameters

Todo getPublic › Responses

Todo getPublicMeta

Todo getPublicMeta › path Parameters

Todo getPublicMeta › Responses

Todo updateStatus

Todo updateStatus › path Parameters

Todo updateStatus › Request Body

Todo updateStatus › Responses

Todo restore

Todo restore › path Parameters

Todo restore › Request Body

Todo restore › Responses

Todo importSession

Todo importSession › Request Body

Todo importSession › Responses

Todo updateMessage

Todo updateMessage › path Parameters

Todo updateMessage › Request Body

Todo updateMessage › Responses

Todo updateAndStart

Todo updateAndStart › path Parameters

Todo updateAndStart › Request Body

Todo updateAndStart › Responses

Todo linkBlockSubTodo

Todo linkBlockSubTodo › path Parameters

Todo linkBlockSubTodo › Request Body

Todo linkBlockSubTodo › Responses

Todo clearBlockResult

Todo clearBlockResult › path Parameters

Todo clearBlockResult › Request Body

Todo clearBlockResult › Responses

Todo toggleBlockChecked

Todo toggleBlockChecked › path Parameters

Todo toggleBlockChecked › Request Body

Todo toggleBlockChecked › Responses

Todo updateAgentMapping

Todo updateAgentMapping › path Parameters

Todo updateAgentMapping › Request Body

Todo updateAgentMapping › Responses

Todo subscribe