Recommendation generate
Ask the Business Analyzer to produce recommendation proposals. direction is a free-text steer sent as a chat message; the run reuses the project's ongoing analyzer chat so steering and dismissal feedback accrue.
path Parameters
projectIdstring · required
Request Body
projectIdstring · required
directionstringFree-text steer sent to the analyzer as a chat message (e.g. "focus on TikTok", "more B2B leads").
Responses
Successful response
todoIdstring · required
Recommendation create
Propose a PROPOSED todo on a project (used by todoforai-cli recommend and the analyzer's api_recommend_template). Pass specId to reuse a registry spec, or template to write the proposal inline — the spec is created here and rolled back if the proposal fails. Re-proposing the same specId refreshes the open proposal instead of duplicating it.
path Parameters
projectIdstring · required
Request Body
projectIdstring · required
kindconstConst value: recommendationspecIdstringReuse an existing registry spec as-is. Exactly one of specId / template.
templateobjecttitlestringnotestringprioritygroupstringBoard group slug (strategic workstream) for the card; upserted on creation.
groupNamestringOptional display name to upsert for
group.groupDescriptionstringOne-line strategic intent to upsert for
group(routes future todos into it).
Responses
Successful response
idstring · requiredprojectIdstring · requiredstatusrequiredagentSettingsIdstring · requiredcontentstring · requiredmessageIdsstring[] · requiredmessagesobject[] · requiredcreatedAtnumber · requiredlastActivityAtnumber · requiredscheduledTimestampnumber · required0 if immediate
groupTagstringProject-scoped group slug.
privateOwnerIdstringSet (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.parentTodoIdstringTodo 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.
systemMessageIdstringcheckedBlockIdsstring[]User-checked blocks
actionableBlockIdsstring[]Blocks with code, commands, etc.
archivedAtnumberdeletedAtnumberdismissedAtnumberWhen the proposal was dismissed — bounds the analyzer's feedback window.
starredAtnumberStar/favorite timestamp; absent/0 = not starred
contributorIdsstring[]Users who sent messages into the todo, in order of first appearance ([0] = creator).
workflowVersionstringFor optimistic concurrency
visiblebooleanVisible in default project listings; defaults to true.
isPublicbooleanPublicly viewable (read-only) by anyone with the link, no login required.
commentsEnabledbooleanSigned-in non-members may comment on a public todo. Members can always comment.
autoDonebooleanPre-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.
statusRevnumberPer-todo transition counter at
status— travels WITH it, so a client knows which transition it holds.hasMoreMessagesbooleanTrue when
messagesholds only the newest page — older ones via todo.getMessages.importSourceobjectProvenance of an imported todo (see ImportSessionInput.source).