Create stream

Create a new append-only stream within a bucket.

bucketpathstringrequired

Bucket ID. Must match [a-z0-9_-]{4,64}.

streampathstringrequired

Stream ID within the bucket. Max 122 bytes; cannot contain /, \0, or ... The literal name streams is reserved (it routes to bucket-level listing). Combined bucket/stream path is also capped at 122 bytes.

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.

If-Matchheaderstring

Conditional create: only succeed if the stream's ETag matches.

Stream-Seqheaderstring

Client-supplied sequence token for conflict detection.

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 with identical configuration (idempotent).
`400`	Invalid stream ID, invalid headers, or bad JSON payload.
`404`	Bucket not found.
`409`	Stream already exists with different configuration, or sequence conflict.
`412`	`If-Match` precondition failed.

Response headers include Location, Content-Type, Stream-Next-Offset, and ETag.

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'

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, or retention, the response is 409 Conflict.