Append records.
curl --request POST \
--url https://{basin}.b.s2.dev/v1/streams/{stream}/records \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"records": [
{
"body": "<string>",
"headers": [
[
"<string>"
]
],
"timestamp": 1
}
]
}
'{
"end": {
"seq_num": 1,
"timestamp": 1
},
"start": {
"seq_num": 1,
"timestamp": 1
},
"tail": {
"seq_num": 1,
"timestamp": 1
}
}{
"code": "<string>",
"message": "<string>"
}{
"code": "<string>",
"message": "<string>"
}{
"code": "<string>",
"message": "<string>"
}{
"code": "<string>",
"message": "<string>"
}{
"code": "<string>",
"message": "<string>"
}{
"fencing_token_mismatch": "<string>"
}records
Append records.
Append a batch of records atomically to an S2 stream, with optional append conditions.
POST
/
streams
/
{stream}
/
records
Append records.
curl --request POST \
--url https://{basin}.b.s2.dev/v1/streams/{stream}/records \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"records": [
{
"body": "<string>",
"headers": [
[
"<string>"
]
],
"timestamp": 1
}
]
}
'{
"end": {
"seq_num": 1,
"timestamp": 1
},
"start": {
"seq_num": 1,
"timestamp": 1
},
"tail": {
"seq_num": 1,
"timestamp": 1
}
}{
"code": "<string>",
"message": "<string>"
}{
"code": "<string>",
"message": "<string>"
}{
"code": "<string>",
"message": "<string>"
}{
"code": "<string>",
"message": "<string>"
}{
"code": "<string>",
"message": "<string>"
}{
"fencing_token_mismatch": "<string>"
}Append concepts
Understand append acknowledgements, batching, and durability.
Concurrency control
Coordinate writers with match sequence numbers and fencing tokens.
Appending SDK
Use append sessions, the Producer API, batching, and backpressure.
Stream config on auto-creation
If the basin hascreate_stream_on_append configured, a stream that does not exist is created on first append with the basin’s default stream config.
The s2-stream-config header can override that default for the new stream. Its value is a JSON-encoded StreamConfig, the same object accepted by create. Unset fields inherit the basin’s default stream config.
The header is only applied when the append creates the stream. It is ignored if the stream already exists, so it is safe to send on every request. To change the config of an existing stream, use reconfigure.
curl --request POST \
--url 'https://{basin}.b.s2.dev/v1/streams/{stream}/records' \
--header "Authorization: Bearer ${S2_ACCESS_TOKEN}" \
--header 'Content-Type: application/json' \
--header 's2-stream-config: {"retention_policy":{"age":3600},"delete_on_empty":{"min_age_secs":300}}' \
--data '{
"records": [
{ "body": "started" }
]
}'
StreamConfig is rejected with a 400 bad_header error. The same header is accepted on read for basins with create_stream_on_read.Authorizations
Headers
Defines the interpretation of record data (header name, header value, and body) with the JSON content type.
Use raw (default) for efficient transmission and storage of Unicode data — storage will be in UTF-8.
Use base64 for safe transmission with efficient storage of binary data.
Available options:
raw, base64 Body
application/json
Payload of an append request.
Response
Success response to an append request.

