Context getContextInfo
Get context window usage information for a specific todo. Returns current token usage, context window size, and whether compaction is recommended.
path Parameters
todoIdstring · required
Responses
Successful response
todoIdstring · requiredThe todo ID this context info belongs to
modelstring · requiredThe model being used
contextWindownumber · requiredMaximum context window size in tokens
usedTokensnumber · requiredCurrent tokens used
utilizationPercentnumber · requiredPercentage of context window used (0-100)
messageCountnumber · requiredNumber of messages in the conversation
shouldCompactboolean · requiredWhether context compaction is recommended
compactingboolean · requiredA compaction request is in flight (agent not yet answered); persisted so it survives reloads
warningLevelrequiredWarning level based on utilization
breakdownobject · requiredToken breakdown for context tracking
Context compact
Analyze or perform context compaction by summarizing older messages. Use dryRun=true (default) to see what would be compacted without making changes.
path Parameters
todoIdstring · required
Request Body
todoIdstring · required
dryRunbooleanIf true, only simulate compaction without making changes
targetUtilizationnumberTarget utilization percentage after compaction (0-1, default 0.5 = 50%)
Responses
Successful response
successboolean · requiredoriginalMessagesnumber · requiredcompactedMessagesnumber · requiredsavedMessagesnumber · required
summarystringmessagestring
Context getSummaries
Get the history of context compaction events for a todo.
path Parameters
todoIdstring · required
Responses
Successful response
outputTokensnumber · requiredToken count after compaction
timestampnumber · requiredWhen compaction happened
messageIdsstring[] · requiredWhich messages were summarized
summarystringPlain summary text. Kept so the divider can display the compaction result directly.
summaryAttachmentobjectBase attachment metadata type - reference only, no content. URI is always required and is the source of truth reference. Format: "todoforai:todos/{todoId}/{id}"
statusStatus: 'ready' = waiting to be used, 'used' = already attached to a message
Context addSummary
Record a context compaction event. Called by the agent after compacting the context. Include summaryAttachment for the summary to be attached to the next message.
path Parameters
todoIdstring · required
Request Body
todoIdstring · requiredoutputTokensnumber · requiredToken count after compaction
timestampnumber · requiredWhen compaction happened
messageIdsstring[] · requiredWhich messages were summarized
summarystringPlain summary text
summaryAttachmentobjectBase attachment metadata type - reference only, no content. URI is always required and is the source of truth reference. Format: "todoforai:todos/{todoId}/{id}"
statusStatus: 'ready' = waiting to be used, defaults to 'ready'
Responses
Successful response
successboolean · required