HTTP Pipeline Channel

A conversation can also be run over a plain HTTP request, without any socket library. The underlying mechanism is identical to the socket transports — the same pipeline, the same session, the same elements — only the framing differs: input is the request body, output is a newline-delimited streaming response.

This channel is intended for text-only integrations, scripting and diagnostics. Audio input and low-latency barge-in require one of the socket transports described in Pipeline Socket.

PUT /api/pipeline/{key}

PUT /api/pipeline/agent:acme-support
Content-Type: text/plain
X-Device-Id: my-integration
Accept-Language: en-US

Who was Isaac Newton?

Parameters

Parameter Required Type Description

key

Yes

String (path)

Pipeline key, e.g. agent:acme-support.

sessionId

No

UUID (cookie or query)

Continues an existing session. Returned as a cookie on every response — see Session Continuity.

any pipeline parameter

No

query or X- header

Every parameter of Pipeline Configuration applies here — locale, time zone, device ref, formats, textOnly and the rest.

Content-Type must be text/plain.

Request Body

Streamed: every line is read as one input element using the connection’s inputFormat (TEXT by default), exactly as over a socket.

Response

text/plain, carrying one serialized output element per line, flushed as it is produced. The stream ends when the engine emits #exit (turn completed) or #error.

GET /api/pipeline/{key}

The same channel for cases where a request body is inconvenient:

GET /api/pipeline/agent:acme-support?text=%23intro

Parameters

Parameter Required Type Description

key

Yes

String (path)

Pipeline key.

text

No

String (query)

The single input element to send. Defaults to #intro, which triggers the agent’s introduction.

sessionId

No

UUID (cookie or query)

Continues an existing session.

any pipeline parameter

No

query or X- header

As for the PUT variant above.

Takes no request body; the response is the same newline-delimited stream.

Session Continuity

The response sets a sessionId cookie holding the session’s UUID. Send it back on the next request — or pass sessionId explicitly as a query parameter — to continue the same conversation across calls. Without it, every request starts a new session.

Because the reverse proxy uses cookie-based affinity, preserving cookies also keeps consecutive requests on the same engine instance.

Example

# start a session and keep the cookie
curl -s -c session.txt "http://localhost:9010/api/pipeline/agent:default?text=%23intro"

# continue the same session
curl -s -b session.txt -X PUT "http://localhost:9010/api/pipeline/agent:default" \
  -H "Content-Type: text/plain" \
  -H "X-Device-Id: my-integration" \
  --data-binary "What time is it?"

Add -H "X-Text-Only: true" to suppress speech synthesis and receive text output only, which makes the response easy to read in a terminal.