Skip to main content

Documentation Index

Fetch the complete documentation index at: https://septemberai.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

POST /execute returns Server-Sent Events. The events fall into four families: lifecycle, content, tool calls, and human-in-the-loop. This page catalogs them. Each event has the shape: 
event: <type>
data: <json>
A blank line terminates each event. The data payload’s exact shape depends on the event type.

​
Lifecycle

​
thread_lifecycle

Emitted at the start and end of every turn. 
{
  "phase": "started" | "completed" | "errored",
  "task_id": "demo-001",
  "turn_id": "...",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
A turn always opens with a started event and closes with completed or errored.

​
error

Emitted when execution fails mid-stream. After this event, no more events will arrive on the current call. 
{
  "error": "LLM_PROVIDER_ERROR",
  "message": "Upstream model returned 500.",
  "details": { /* optional */ }
}

​
Content

​
text_delta

A chunk of model output text. Concatenate all text_delta events in order to get the full response. 
{
  "text": "Hello, "
}

​
thinking_delta

A chunk of the model’s internal reasoning when extended thinking is on. Treat the same way as text_delta but render in a separate UI region (or hide entirely if you don’t surface thinking to users). 
{
  "text": "Let me think about this..."
}

​
content_block_start / content_block_stop

Emitted around content blocks (text, thinking, tool use). Useful when you need to track block boundaries — for example, to emit a UI separator. 
{
  "block_index": 0,
  "block_type": "text" | "thinking" | "tool_use"
}

​
Tool execution

​
tool_call

The model has decided to call a tool. The input field contains whatever the model provided as arguments. 
{
  "tool": "bash",
  "tool_call_id": "...",
  "input": {
    "command": "ls -la"
  }
}

​
tool_result

The tool finished. output holds whatever the tool returned. May include an error field if the call failed. 
{
  "tool": "bash",
  "tool_call_id": "...",
  "output": "drwxr-xr-x  6 ...",
  "error": null
}

​
Human-in-the-loop

​
hitl_request

The agent has paused and needs your answer. Reply with POST /hitl/respond using the request_id. Until you reply, the stream will continue to emit other events (heartbeats) but will not proceed. 
{
  "request_id": "hitl-...",
  "kind": "question" | "permission",
  "question": "Should I delete the file foo.txt?",
  "context": { /* the agent's view of why it's asking */ },
  "options": ["yes", "no"]
}

​
hitl_resolved

Emitted after POST /hitl/respond to signal that the loop has resumed. 
{
  "request_id": "hitl-...",
  "answer": "yes"
}

​
Memory and context

​
working_memory_update

Emitted when the agent writes to working memory. 
{
  "entry_type": "note" | "observation" | "summary",
  "content": "..."
}

​
compaction_event

Emitted when the compaction orchestrator collapses earlier turns. 
{
  "before_tokens": 24000,
  "after_tokens": 8500,
  "strategy": "summary" | "structured_extraction"
}

​
Diagnostic

​
heartbeat

Periodic. Use to detect dead connections client-side. 
{
  "now": "2026-04-27T12:34:56.000Z"
}

​
usage

Token usage so far for the turn. 
{
  "input_tokens": 1240,
  "output_tokens": 312,
  "cache_hit_tokens": 980
}

​
Notes for client implementers

  • Missing event: lines. Some clients omit the event: line and only send data:. The Engine always emits event:. Use it to route.
  • Reordering. Events are emitted in execution order. Don’t try to reorder them.
  • Multiple text streams. A single turn can emit text from multiple tool calls and thinking blocks. Use content_block_start / content_block_stop to separate them.
  • Disconnections. If your client disconnects mid-stream, use GET /execute/replay?after=<ts> to fetch missed events.

​
See also