Skip to main content
POST
/
defend
/
{workflow_id}
/
events?stream=true
Create a Streaming Workflow Event
import httpx
import json

DEEPRAILS_API_KEY = "YOUR_API_KEY"
workflow_id = "wkfl_xxxxxxxxxxxx"

url = f"https://api.deeprails.com/defend/{workflow_id}/events?stream=true"
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {DEEPRAILS_API_KEY}",
}
payload = {
    "model_input": {"prompt": "Christmas Day was filled with festive broadcasting but what was 2025’s most-watched programme in the UK?"},
    "model_output": "The Celebrity Traitors.",
    "model_used": "gpt-4",
    "run_mode": "precision",
}

with httpx.stream("POST", url, json=payload, headers=headers, timeout=120.0) as response:
    event_type = None
    data_buffer = []

    for line in response.iter_lines():
        if line.startswith("event:"):
            event_type = line[6:].strip()
        elif line.startswith("data:"):
            data_buffer.append(line[5:].strip())
        elif line == "" and event_type:
            data = json.loads("".join(data_buffer))

            if event_type == "token":
                print(data["content"], end="", flush=True)
            elif event_type == "error":
                print(f"Error: {data['message']}")
                break

            event_type = None
            data_buffer = []
{
  "event": "token",
  "data": {
    "content": "The Celebrity"
  }
}

​
Why use streaming?

By default, when you submit a workflow event, the response is delivered all at once after processing completes. Streaming lets you start receiving outputs immediately, before processing is entirely finished — perfect for chat interfaces or any application where perceived latency matters.

​
How it works

Add stream=true to your request, and you’ll receive a stream of Server-Sent Events instead of a single JSON response.

Streaming is supported on all run modes except precision_max and precision_max_codex.

Note: ultra_fast and super_fast do not support Web Search or File Search. If your workflow has these capabilities enabled, either switch to a run mode that supports them (e.g. fast, precision, precision_codex) or edit the workflow to disable Web Search / File Search.

Defend evaluates the model output against your workflow’s guardrails. If the output passes, it streams back the original. If it fails, Defend improves it and streams back the improved version. Either way, you receive a single stream of token events containing the final output — just forward them to your end-user.

​
Event types

– token: These are the output chunks. Stream them directly to your end-user as they arrive.

– error: This means something went wrong, and will include a message.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
workflow_id
string
required

The ID of the workflow to create the event for.

Query Parameters

​
stream
boolean
default:false

Enable SSE streaming for real-time token feedback. Supported on all run modes except precision_max and precision_max_codex.

Body

application/json
​
model_input
object
required

The input provided to the model (e.g., prompt, messages).

​
model_output
string
required

The output generated by the model to be evaluated.

​
model_used
string
required

The model that generated the output (e.g., "gpt-4", "claude-3").

​
run_mode
enum<string>
required

The evaluation run mode. Streaming is supported on all run modes except precision_max and precision_max_codex. Note: ultra_fast and super_fast do not support Web Search or File Search — if your workflow has these enabled, use a different run mode or disable the capability on the workflow.

Available options:
ultra_fast,
super_fast,
fast,
precision,
precision_codex
​
nametag
string

Optional tag to identify this event.

Response

A stream of Server-Sent Events delivering the output directly to your end-user.

Each event has an event: type and a data: JSON payload. You'll receive:

– token — Output chunks. Stream these directly to your end-user as they arrive. If the original output passed all guardrails, the tokens contain the original. If improvement was needed, the tokens contain the improved version. Either way, you should forward them.

– error — This means something went wrong and includes a message field.

The response is of type string<sse>.