SSE Events Reference¶

Complete reference for all Server-Sent Events emitted by the Nodexa streaming API (stream: true).

Event Format¶

Each event is sent as two lines followed by a blank line:

event: <event-type>
data: <json-payload>

The stream ends with:

data: [DONE]

Heartbeat¶

Every 15 seconds of inactivity, a comment line is sent to keep the connection alive:

: heartbeat

SSE comments (lines starting with :) are ignored by standard parsers.

Event Index¶

Event	Description
`response.created`	Stream started, processing begins
`response.status`	Processing status update
`response.output_text.delta`	Text token from the assistant
`response.reasoning_summary_text.delta`	Reasoning summary token (reasoning models only)
`response.function_call_arguments.delta`	Partial function call arguments
`response.function_call_arguments.done`	Function call arguments complete
`response.output_item.added`	New output item added (message, handover, oauth_required)
`response.output_item.done`	Output item complete
`response.web_search_call.in_progress`	Web search starting
`response.web_search_call.searching`	Web search query submitted
`response.web_search_call.completed`	Web search results ready
`response.completed`	Response fully complete
`response.error`	Error occurred, stream closing

Event Details¶

`response.created`¶

Emitted immediately when the platform starts processing the request.

{
  "type": "response.created",
  "response": {
    "id": "resp_01234567-89ab-cdef-0123-456789abcdef",
    "status": "in_progress"
  }
}

Field	Type	Description
`type`	`string`	Always `"response.created"`
`response.id`	`string`	Unique response ID for threading
`response.status`	`string`	Always `"in_progress"` at this point

Use case: Show a loading/typing indicator.

`response.status`¶

Emitted when internal processing status changes (e.g., routing to a specialist agent, loading tools, running retrieval).

{
  "type": "response.status",
  "status": "processing"
}

Field	Type	Description
`type`	`string`	Always `"response.status"`
`status`	`string`	Current status description

`response.output_text.delta`¶

Emitted for each text token. Concatenate all delta values to reconstruct the full text.

{
  "type": "response.output_text.delta",
  "delta": " world"
}

Field	Type	Description
`type`	`string`	Always `"response.output_text.delta"`
`delta`	`string`	Token(s) to append to the current text buffer

Use case: Append each delta to your text display buffer.

let textBuffer = '';
if (event.type === 'response.output_text.delta') {
  textBuffer += event.delta;
  updateUI(textBuffer);
}

`response.reasoning_summary_text.delta`¶

Emitted during the reasoning phase of models that expose a reasoning summary (e.g., OpenAI o1, o3-mini). These tokens represent the model's visible thinking process, not the final answer.

{
  "type": "response.reasoning_summary_text.delta",
  "delta": "The user is asking about the history of"
}

Field	Type	Description
`type`	`string`	Always `"response.reasoning_summary_text.delta"`
`delta`	`string`	Reasoning summary token(s)

Use case: Optionally display a "thinking..." section. These tokens arrive before response.output_text.delta events.

Note

Only emitted by reasoning models. Not present for standard chat models.

`response.function_call_arguments.delta`¶

Emitted as the model generates JSON arguments for a function call. Useful for showing a "preparing to call tool" indicator.

{
  "type": "response.function_call_arguments.delta",
  "delta": "{\"city\": \"Par"
}

Field	Type	Description
`type`	`string`	Always `"response.function_call_arguments.delta"`
`delta`	`string`	Partial JSON arguments string

Use case: Display a tool-calling indicator in the UI.

`response.function_call_arguments.done`¶

Emitted when the function call arguments are fully assembled. This is the event that triggers client-side tool execution.

{
  "type": "response.function_call_arguments.done",
  "name": "get_weather",
  "call_id": "call_abc123",
  "arguments": "{\"city\": \"Paris\", \"unit\": \"celsius\"}"
}

Field	Type	Description
`type`	`string`	Always `"response.function_call_arguments.done"`
`name`	`string`	Name of the function to call
`call_id`	`string`	Unique ID for this call — include in `function_call_output`
`arguments`	`string`	Complete JSON-encoded arguments string

Use case: Parse arguments, execute the function, collect the call_id, then send a follow-up request. See Function Calling.

`response.output_item.added`¶

Emitted when the model adds a structured item to its output array. The item.type determines what kind of item it is.

Message item¶

{
  "type": "response.output_item.added",
  "item": {
    "type": "message",
    "role": "assistant",
    "content": []
  }
}

Handover item¶

Emitted when control is transferred from one specialist agent to another.

{
  "type": "response.output_item.added",
  "item": {
    "type": "handover",
    "from_specialist": "General Assistant",
    "to_specialist": "Technical Support",
    "reason": "User is asking about API integration details"
  }
}

Field	Type	Description
`item.type`	`"handover"`	Identifies this as a handover notification
`item.from_specialist`	`string`	Display name of the specialist agent that was active
`item.to_specialist`	`string`	Display name of the specialist agent that took over
`item.reason`	`string`	Explanation of why the handover occurred

Use case: Log routing information or show a "connecting you to [specialist agent]" notice.

OAuth required item¶

Emitted when a tool requires OAuth credentials that are not present in the request.

{
  "type": "response.output_item.added",
  "item": {
    "type": "oauth_required",
    "plugin_id": "plugin_abc123",
    "plugin_name": "Google Calendar",
    "provider_id": "google",
    "required_scopes": ["https://www.googleapis.com/auth/calendar.readonly"],
    "auth_url": "https://your-admin.example.com/oauth/google/authorize?state=xyz"
  }
}

Field	Type	Description
`item.type`	`"oauth_required"`	Identifies this as an OAuth prompt
`item.plugin_id`	`string`	Internal plugin identifier
`item.plugin_name`	`string`	Human-readable plugin name
`item.provider_id`	`string`	OAuth provider identifier (e.g., `"google"`)
`item.required_scopes`	`string[]`	OAuth scopes needed
`item.auth_url`	`string`	URL to start the OAuth authorization flow

Use case: Redirect the user to auth_url, then retry the request with the obtained token in x-user-tokens.

`response.output_item.done`¶

Emitted when an output item is fully assembled (after all delta events for that item).

{
  "type": "response.output_item.done",
  "item": {
    "type": "message",
    "role": "assistant",
    "content": [
      {
        "type": "output_text",
        "text": "The complete assembled response text."
      }
    ]
  }
}

Field	Type	Description
`type`	`string`	Always `"response.output_item.done"`
`item`	`object`	The fully assembled output item

`response.web_search_call.in_progress`¶

Emitted when a web search tool is invoked and the search is about to begin.

{
  "type": "response.web_search_call.in_progress",
  "call_id": "ws_call_abc123"
}

Field	Type	Description
`type`	`string`	Always `"response.web_search_call.in_progress"`
`call_id`	`string`	Unique identifier for this search call

`response.web_search_call.searching`¶

Emitted when the search query has been determined and submitted.

{
  "type": "response.web_search_call.searching",
  "call_id": "ws_call_abc123",
  "query": "latest AI regulation news 2024"
}

Field	Type	Description
`type`	`string`	Always `"response.web_search_call.searching"`
`call_id`	`string`	Identifier for this search call
`query`	`string`	The search query submitted

Use case: Display "Searching for: [query]" in your UI.

`response.web_search_call.completed`¶

Emitted when search results are available and being incorporated.

{
  "type": "response.web_search_call.completed",
  "call_id": "ws_call_abc123",
  "results_count": 5
}

Field	Type	Description
`type`	`string`	Always `"response.web_search_call.completed"`
`call_id`	`string`	Identifier for this search call
`results_count`	`number`	Number of search results found

`response.completed`¶

Emitted when the full response is complete and the stream is about to close. Contains the complete response object.

{
  "type": "response.completed",
  "response": {
    "id": "resp_01234567-89ab-cdef-0123-456789abcdef",
    "object": "response",
    "status": "completed",
    "model": "asst_01234567-89ab-cdef-0123-456789abcdef",
    "output_text": "The complete response text.",
    "output": [
      {
        "type": "message",
        "role": "assistant",
        "content": [
          {
            "type": "output_text",
            "text": "The complete response text."
          }
        ]
      }
    ],
    "created_at": 1700000000
  }
}

Field	Type	Description
`type`	`string`	Always `"response.completed"`
`response.id`	`string`	Unique response ID — save for conversation threading
`response.status`	`string`	`"completed"` or `"requires_action"`
`response.output_text`	`string`	Convenience field with full assembled text
`response.output`	`array`	Full structured output array
`response.created_at`	`number`	Unix timestamp

requires_action in response.completed

If response.status is "requires_action", the assistant called a client-side function tool and is waiting for results. You must execute the function and send a follow-up request. See Function Calling.

`response.error`¶

Emitted when a fatal error occurs during streaming. The stream closes after this event.

{
  "type": "response.error",
  "error": {
    "type": "server_error",
    "code": "upstream_timeout",
    "message": "The LLM provider did not respond within the timeout period."
  }
}

Field	Type	Description
`type`	`string`	Always `"response.error"`
`error.type`	`string`	Error category (e.g., `"server_error"`, `"invalid_request_error"`)
`error.code`	`string`	Machine-readable error code
`error.message`	`string`	Human-readable error description

See Errors for all error codes and their meanings.

Typical Event Sequence¶

Simple text response¶

response.created
response.output_item.added    (type: message)
response.output_text.delta    (repeated N times)
response.output_item.done
response.completed
[DONE]

Response with web search¶

response.created
response.web_search_call.in_progress
response.web_search_call.searching
response.web_search_call.completed
response.output_item.added    (type: message)
response.output_text.delta    (repeated N times)
response.output_item.done
response.completed
[DONE]

Response with specialist agent handover¶

response.created
response.output_item.added    (type: handover)
response.output_item.done
response.output_item.added    (type: message)
response.output_text.delta    (repeated N times)
response.output_item.done
response.completed
[DONE]

Response requiring function call¶

response.created
response.output_item.added    (type: function_call - not usually emitted separately)
response.function_call_arguments.delta  (repeated)
response.function_call_arguments.done
response.completed            (status: requires_action)
[DONE]

Response with reasoning (reasoning models)¶

response.created
response.reasoning_summary_text.delta  (repeated)
response.output_item.added    (type: message)
response.output_text.delta    (repeated N times)
response.output_item.done
response.completed
[DONE]

SSE Events Reference¶

Event Format¶

Heartbeat¶

Event Index¶

Event Details¶

response.created¶

response.status¶

response.output_text.delta¶

response.reasoning_summary_text.delta¶

response.function_call_arguments.delta¶

response.function_call_arguments.done¶

response.output_item.added¶

Message item¶

Handover item¶

OAuth required item¶

response.output_item.done¶

response.web_search_call.in_progress¶

response.web_search_call.searching¶

response.web_search_call.completed¶

response.completed¶

response.error¶

Typical Event Sequence¶

Simple text response¶

Response with web search¶

Response with specialist agent handover¶

Response requiring function call¶

Response with reasoning (reasoning models)¶

`response.created`¶

`response.status`¶

`response.output_text.delta`¶

`response.reasoning_summary_text.delta`¶

`response.function_call_arguments.delta`¶

`response.function_call_arguments.done`¶

`response.output_item.added`¶

`response.output_item.done`¶

`response.web_search_call.in_progress`¶

`response.web_search_call.searching`¶

`response.web_search_call.completed`¶

`response.completed`¶

`response.error`¶