Reference
HTTP API Every request, header, and status code for using Durable Streams over plain HTTP.
Every stream is a URL, and every operation is a plain HTTP request on it:
http://127.0.0.1:8642/durable-streams/v1/stream/<path> Any HTTP client works, and existing Durable Streams clients work unchanged. The Durable Streams protocol covers every edge case.
Method Does Notes PUTCreate a stream Body is optional initial data. Repeating the same PUT is safe; a different configuration returns 409. POSTAppend Body is the data, in the stream’s content type. GETRead Starts at the offset query parameter. Add live to wait for new data. HEADRead metadata Content type, end offset, expiry, and whether the stream is closed. DELETEDelete the stream and its history
STREAM = http://127.0.0.1:8642/durable-streams/v1/stream/chat/session-1 curl -X PUT -H 'content-type: application/json' $STREAM curl -X POST -H 'content-type: application/json' --data '{"token":"hello"}' $STREAM curl " $STREAM ?offset=-1" curl -I $STREAM curl -X DELETE $STREAM Request header Use content-typeThe stream’s format, fixed for its lifetime. application/json stores separate messages; anything else stores bytes. Stream-TTLDelete after this many seconds with no reads or writes. Stream-Expires-AtDelete at an RFC 3339 timestamp. Use one of Stream-TTL or Stream-Expires-At, not both. Stream-Forked-FromCreate a fork of the stream at this path. Stream-Fork-OffsetFork from this offset instead of the end.
In a JSON stream, posting a JSON array stores each element as its own message, so one request can carry a batch.
Request header Use Producer-IdStable name of an idempotent writer. Producer-EpochThe writer’s session. Raise it when the writer restarts; requests with an older epoch return 403. Producer-SeqStarts at 0 and goes up by one per request in the epoch. A repeated sequence returns 204 and writes nothing. Send all three producer headers or none. Stream-SeqYour own ordering value. A value not greater than the last one returns 409. Compared as strings. Stream-Closed: trueClose the stream, with or without a final message in the body.
Query parameter Use offsetWhere to start: an offset from a previous read, -1 for the beginning, or now for the end. livesse or long-poll to wait for new data. Omit for a one-off read.
Response header Meaning Stream-Next-OffsetPass this as offset on the next read. Stream-Up-To-Date: trueYou have everything written so far. Stream-Closed: trueNothing more will ever arrive.
live=ssedata events carry messages and control events carry streamNextOffset, upToDate, and closed status. The server ends connections periodically; reconnect from the last streamNextOffset. For byte streams, data is base64-encoded and the response carries stream-sse-data-encoding: base64.live=long-poll204 on timeout; retry with the same offset.
curl -N " $STREAM ?offset=-1&live=sse" Code Meaning 200, 201Success, such as a read or a new stream. 204Success with no body, such as an append or close. Also returned for a duplicate producer write and a long-poll timeout. 403Producer epoch is older than the current one. 404The stream does not exist. 409Stream exists with a different configuration, is closed, or Stream-Seq went backwards.