Run a Pipeline with the Worker GatewayBeta

Beta

This is coming — this page describes a feature that's still being rolled out and may not be available to you yet.

The worker gateway lets you run a Haystack pipeline YAML directly through the API without creating or deploying a pipeline first. You supply the pipeline definition as a YAML string, and the platform executes it immediately and returns the results as Server-Sent Events (SSE).

Use it to test pipelines, run one-off tasks, or run pipelines from your own applications.

---

About This Feature

Along with the pipeline YAML, you send the runtime inputs. The endpoint runs the pipeline in a fresh subprocess for each request, so no state carries over between requests.

The workspace endpoint automatically merges your workspace environment variables and patches document store configurations, so your pipeline can access the same secrets and indexes you have configured in the workspace.

Endpoint:

POST /workspaces/{workspace_name}/haystack/worker-gateway/stream

The response is always an SSE stream, regardless of whether you set include_result to true or false.

Request Fields

The request body is JSON with these fields:

Field	Required	Description
pipeline_yaml (alias YAML)	Yes	The full pipeline YAML definition as a string.
inputs	No	Inputs passed to Pipeline.run().
deps	No	Extra Python packages to install before running the pipeline, specified as a list of uv --with requirements.
env	No	Per-request environment variables to set during execution.
haystack_version	No	Explicit haystack-ai version to use.
streaming_components	No	null, "all", or an array of component names to stream output from.
include_result	No	Set to true to receive the final pipeline result as a result SSE event.
emit_tool_call_events	No	Set to true to receive tool call events when the pipeline includes an Agent.
emit_reasoning_events	No	Set to true to receive reasoning events when the pipeline includes an Agent.
include_outputs_from	No	Components whose outputs to include in the final result.
allow_sync_streaming_callbacks	No	Set to true to stream from components that only support sync callbacks.
pipeline_end_message	No	Final text chunk sent before the result event.

SSE Event Types

The endpoint streams results as these SSE event types:

Event type	Description
delta	A content chunk from a streaming-capable component, such as an LLM.
result	The final pipeline output. Sent when include_result is true or streaming completes.
error	An error message if pipeline execution fails.
tool_call_delta	Signals the start of a tool call from an Agent component.
tool_call_result	Returns the result of a tool call from an Agent component.
reasoning	A reasoning step emitted by an Agent component.

Run a Pipeline Without Streaming

To get just the final result, set include_result to true. The endpoint runs the pipeline and returns a single result SSE event.

curl -N -sS -X POST "$HUB_API_URL/workspaces/$WORKSPACE/haystack/worker-gateway/stream" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline_yaml": "components:\n  llm:\n    type: LLM\n    init_parameters:\n      model: gpt-4o-mini\nconnections: []\n",
    "inputs": {
      "llm": {
        "messages": [{"role": "user", "content": "Hello"}]
      }
    },
    "include_result": true
  }'

Example SSE response:

data: {"type": "result", "result": {"llm": {"replies": ["Hello! How can I help you today?"]}}}

Run a Pipeline with Streaming

To show output to your users while the pipeline is still generating it, omit include_result or set it to false. Set streaming_components to "all" to stream from every component that supports it.

curl -N -sS -X POST "$HUB_API_URL/workspaces/$WORKSPACE/haystack/worker-gateway/stream" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline_yaml": "components:\n  llm:\n    type: LLM\n    init_parameters:\n      model: gpt-4o-mini\nconnections: []\n",
    "inputs": {
      "llm": {
        "messages": [{"role": "user", "content": "What is Haystack?"}]
      }
    },
    "streaming_components": "all"
  }'

Example SSE events:

data: {"type": "delta", "delta": {"text": "Haystack"}}

data: {"type": "delta", "delta": {"text": " is an open source"}}

data: {"type": "result", "result": {"llm": {"replies": ["Haystack is an open source AI framework."]}}}

Authentication

The workspace endpoint requires the same authentication as other workspace-scoped endpoints:

• Authorization: Bearer $TOKEN — your workspace API token.
• X-User-Info: $X_USER_INFO — user context header, if required by your deployment.

What To Do Next

• To run an already-deployed pipeline through the API, see Test Your Pipeline in Playground.
• To enable streaming on a deployed pipeline, see Enable Streaming.