Create stream

bucketpathstringrequired

Bucket ID. The Durable Streams Protocol specifies [a-z0-9_-]{4,64}. Ursula does not currently enforce this regex but client-side conformance is recommended.

streampathstringrequired

Stream ID within the bucket. Cannot contain \0 and segments cannot equal ... Note: Ursula does not currently enforce the Durable Streams Protocol's 122-byte stream-ID ceiling - clients should still respect it for conformance.

Content-Typeheaderstring

Content type of the initial payload (e.g. application/json). Becomes the stream's content type.

Stream-Closedheaderstring

Set to true to close the stream immediately after creation.

Stream-TTLheaderstring

Time-to-live in seconds. The stream will expire after this duration.

Stream-Expires-Atheaderstring

Absolute expiration timestamp (RFC 3339). Mutually exclusive with Stream-TTL.

Stream-Seqheaderstring

Client-supplied monotonic sequence token. Rejects creates whose Stream-Seq is not lexicographically greater than the previous value seen for this stream.

Stream-Attrsheaderstring

JSON stream attributes. See stream attributes. If the stream already exists, the submitted attributes must match the stored attributes for the create request to be idempotent.

Producer-Idheaderstring

Producer identity for exactly-once writes.

Producer-Epochheaderstring

Producer epoch (must accompany Producer-Id).

Producer-Seqheaderstring

Producer sequence number (must accompany Producer-Id).

bodybodybinary

Optional initial payload. If provided, becomes the first entry in the stream.

Response

Status	Meaning
`201`	Stream created.
`200`	Stream already exists (idempotent).
`400`	Invalid stream ID, invalid headers, or bad JSON payload.
`409`	Stream already exists with different content type, or sequence conflict.

Response headers include Location, Content-Type, Stream-Next-Offset, and lifetime headers (Stream-TTL / Stream-Expires-At) when set. Stream-Closed: true is set if the create request also closed the stream. ETag is set on reads only.

When the initial payload creates records in an application/json stream advertising json-record-coordinates-v1, the response also includes Stream-Record-Start and Stream-Record-Next. A top-level JSON array creates one record per element.

curl -X PUT http://127.0.0.1:4437/demo/hello

curl -X PUT http://127.0.0.1:4437/demo/hello \
  -H 'Content-Type: application/json' \
  --data-binary '{"msg": "first entry"}'

curl -X PUT http://127.0.0.1:4437/demo/ephemeral \
  -H 'Stream-TTL: 3600'

curl -X PUT http://127.0.0.1:4437/demo/session-1 \
  -H 'Stream-Attrs: {"title":"Support session","metadata":{"purpose":"customer-support"}}'

If a stream with the same ID already exists and has identical configuration, the response is 200 OK (idempotent). If the existing stream differs in content type, closed state, retention, or stream attributes, the response is 409 Conflict.

See Record Coordinates for JSON record ranges and complete-record replay.