Blend AI Documentation

Both POST /api/v1/responses (with stream: true) and GET /api/v1/runs/{runId}/stream open a Server-Sent Events (SSE) connection. SSE is a plain HTTP response with Content-Type: text/event-stream — every event is a data: line followed by a blank line.

data: {"type":"response.created","response":{...}}

data: {"type":"response.output_item.added","item":{...}}

data: {"type":"response.completed","response":{...}}

data: [DONE]

The connection closes after data: [DONE]. If it drops earlier, you can resume with GET /runs/{runId}/stream using the same run_id.

Event types

Every event is a JSON object with a type field. Events fall into three groups: lifecycle, output, and terminal.

Lifecycle

event

Sent immediately after POST /responses connects. Use its response.id and response.run_id to correlate downstream events or resume later.

{
    "type": "response.created",
    "response": {
        "id": "resp_run_xyz",
        "run_id": "run_xyz",
        "created_at": 1734567890,
        "workflow_id": "pub_abc123",
        "service_tier": null
    }
}

event

Sent immediately after GET /runs/{runId}/stream connects. Includes the current status so you know whether you’re attaching mid-run or to something already terminal.

{
    "type": "response.resumed",
    "response": {
        "id": "resp_run_xyz",
        "run_id": "run_xyz",
        "status": "running"
    }
}

Output

event

Progress event indicating that the response stream opened an output item. This is not the final itemized workflow output shape; read GET /api/v1/runs/{runId} after completion for Result fields, output items, and parts.

{
    "type": "response.output_item.added",
    "output_index": 0,
    "item": {
        "type": "message",
        "id": "msg_run_xyz",
        "phase": "final_answer"
    }
}

event

Progress event indicating that the streamed output item closed. Same shape as added.

Terminal

event

Run finished successfully. Followed by data: [DONE] and connection close.

{
    "type": "response.completed",
    "response": {
        "usage": null,
        "service_tier": null
    }
}

To read the actual output, call GET /api/v1/runs/{runId} and read the output object. Streaming delivers progress events; the final structured output lives on the run record.

event

Run failed. Followed by data: [DONE] and connection close.

{
    "type": "response.failed",
    "response": {
        "error": {
            "code": null,
            "message": "Workflow failed."
        },
        "incomplete_details": {
            "reason": "error"
        },
        "usage": null,
        "service_tier": null
    }
}

Keepalive

The server emits SSE comment lines (: keepalive) every 15 seconds to prevent proxies and CDNs from closing idle connections during long-running steps. Ignore them — any line starting with : is a comment.

Consuming the stream

Browser

const res = await fetch('https://tryblend.ai/api/v1/responses', {
    method: 'POST',
    headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({ workflowId: 'pub_abc123', stream: true, inputs: { prompt: 'hi' } }),
})

const reader = res.body!.getReader()
const decoder = new TextDecoder()
let buffer = ''

while (true) {
    const { value, done } = await reader.read()
    if (done) break
    buffer += decoder.decode(value, { stream: true })

    const frames = buffer.split('\n\n')
    buffer = frames.pop() ?? ''

    for (const frame of frames) {
        const line = frame.split('\n').find(l => l.startsWith('data: '))
        if (!line) continue

        const payload = line.slice(6)
        if (payload === '[DONE]') return

        const event = JSON.parse(payload)
        handleEvent(event)
    }
}

Node / Python

Both have solid SSE libraries — eventsource for Node, httpx + sseclient for Python. The semantics are the same: parse each data: line as JSON and branch on type.

Resuming a dropped stream

If your connection drops mid-run, don’t re-POST — that starts a new run (and bills you again). Instead, reconnect with the run_id from response.created:

curl https://tryblend.ai/api/v1/runs/run_xyz/stream \
    -H "Authorization: Bearer bai_..."

The first event will be response.resumed. If the run already finished while you were disconnected, you’ll get the terminal event and [DONE] on the next poll tick (~1 second).

Introduction

Endpoints

Streaming

Event types

Lifecycle

Output

Terminal

Keepalive

Consuming the stream

Browser

Node / Python

Resuming a dropped stream

​Event types

​Lifecycle

​Output

​Terminal

​Keepalive

​Consuming the stream

​Browser

​Node / Python

​Resuming a dropped stream

Event types

Lifecycle

Output

Terminal

Keepalive

Consuming the stream

Browser

Node / Python

Resuming a dropped stream