> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deeprails.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Stream a Workflow Event (Optimized)
> Use this endpoint to submit a model input and output pair to a workflow for evaluation with streaming responses.
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: super\_fast does 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.
## OpenAPI
````yaml /api-reference/openapi.yaml post /defend/{workflow_id}/events?stream=true
openapi: 3.0.0
info:
title: DeepRails API
description: >
DeepRails is a powerful developer tool with a comprehensive set of adaptive
& accurate guardrails to protect against LLM hallucinations - deploy our
Monitor and Defend APIs in less than 15 minutes for the best out-of-the-box
guardrails available.
version: v3.0
contact:
name: DeepRails Support
email: support@deeprails.ai
servers:
- url: https://api.deeprails.com
description: Production server
security:
- BearerAuth: []
paths:
/defend/{workflow_id}/events?stream=true:
post:
tags:
- Defend
summary: Stream a Workflow Event (Optimized)
description: >
Use this endpoint to submit a model input and output pair to a workflow
for evaluation with streaming responses.
parameters:
- name: workflow_id
in: path
description: The ID of the workflow to create the event for.
required: true
schema:
type: string
- name: stream
in: query
description: >-
Enable SSE streaming for real-time token feedback. Supported on all
run modes except precision_max and precision_max_codex.
required: false
schema:
type: boolean
default: false
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- model_input
- model_output
- model_used
- run_mode
properties:
model_input:
type: object
description: The input provided to the model (e.g., prompt, messages).
additionalProperties: true
model_output:
type: string
description: The output generated by the model to be evaluated.
model_used:
type: string
description: >-
The model that generated the output (e.g., "gpt-4",
"claude-3").
run_mode:
type: string
description: >
The evaluation run mode. Streaming is supported on all run
modes except precision_max and precision_max_codex. Note:
super_fast does 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.
enum:
- super_fast
- fast
- precision
- precision_codex
nametag:
type: string
description: Optional tag to identify this event.
responses:
'200':
description: >
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.
content:
text/event-stream:
schema:
type: string
format: sse
examples:
Token Event:
summary: A single token chunk
value:
event: token
data:
content: The Celebrity
Error Event:
summary: An error during processing
value:
event: error
data:
message: Workflow not found
'400':
description: >-
Bad Request - Run mode not supported for streaming, or incompatible
capabilities
content:
application/json:
schema:
$ref: 10430970-c28f-4828-9355-2bc91cda64de
examples:
Error - Unsupported Run Mode:
summary: Run mode does not support streaming
value:
event: error
data:
message: >-
Streaming is not supported for run mode 'precision_max'.
Streaming supports all run modes except precision_max
and precision_max_codex.
code: UNSUPPORTED_RUN_MODE
recoverable: false
Error - Incompatible Capabilities:
summary: Run mode does not support workflow capabilities
value:
event: error
data:
message: >-
Run mode 'super_fast' does not support Web Search or
File Search. Either switch to a run mode that supports
these capabilities (fast, precision, precision_codex,
precision_max, or precision_max_codex) or edit the
workflow to disable Web Search / File Search.
code: INCOMPATIBLE_RUN_MODE
recoverable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: 10430970-c28f-4828-9355-2bc91cda64de
examples:
Error - Unauthorized:
summary: Unauthorized
value:
detail: Token has expired
'404':
description: Workflow not found
content:
application/json:
schema:
$ref: 10430970-c28f-4828-9355-2bc91cda64de
examples:
Error - Workflow Not Found:
summary: Workflow Not Found
value:
event: error
data:
message: Workflow not found
code: NOT_FOUND
recoverable: false
security:
- BearerAuth: []
x-codeSamples:
- lang: python
label: Create a Streaming Workflow Event
source: >
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 = []
- lang: javascript
label: Create a Streaming Workflow Event (JavaScript)
source: |
const DEEPRAILS_API_KEY = "YOUR_API_KEY";
const workflowId = "wkfl_xxxxxxxxxxxx";
const response = await fetch(
`https://api.deeprails.com/defend/${workflowId}/events?stream=true`,
{
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": `Bearer ${DEEPRAILS_API_KEY}`,
},
body: JSON.stringify({
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",
}),
}
);
const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = "";
let currentEvent = "";
let dataBuffer = [];
while (true) {
const { done, value } = await reader.read();
if (done) break;
buffer += decoder.decode(value, { stream: true });
const lines = buffer.split("\n");
buffer = lines.pop() || "";
for (const line of lines) {
if (line.startsWith("event:")) {
currentEvent = line.slice(6).trim();
} else if (line.startsWith("data:")) {
dataBuffer.push(line.slice(5).trim());
} else if (line === "" && currentEvent) {
const data = JSON.parse(dataBuffer.join(""));
if (currentEvent === "token") {
process.stdout.write(data.content);
} else if (currentEvent === "error") {
console.error(`Error: ${data.message}`);
break;
}
currentEvent = "";
dataBuffer = [];
}
}
}
- lang: curl
label: Create a Streaming Workflow Event (cURL)
source: |
curl -N \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"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"
}' \
"https://api.deeprails.com/defend/wkfl_xxxxxxxxxxxx/events?stream=true"
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````