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 records.
Append a batch of records atomically to an S2 stream, with optional append conditions.
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
Concurrency control
Appending SDK
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
Bearer authentication header of the form Bearer <token>, where <token> is your access token.
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.
raw, base64 Encryption key material for append and read operations. Provide base64-encoded key when stream encryption is enabled.
Path Parameters
Stream name.
1 - 512Body
Payload of an append request.
Batch of records to append atomically, which must contain at least one record, and no more than 1000. The total size of a batch of records may not exceed 1 MiB of metered bytes.
Show child attributes
Show child attributes
Enforce a fencing token, which starts out as an empty string that can be overridden by a fence command record.
36Enforce that the sequence number assigned to the first record matches.
x >= 0Response
Success response to an append request.
Sequence number of the last record that was appended + 1, and timestamp of the last record that was appended.
The difference between end.seq_num and start.seq_num will be the number of records appended.
Show child attributes
Show child attributes
Sequence number and timestamp of the first record that was appended.
Show child attributes
Show child attributes
Sequence number that will be assigned to the next record on the stream, and timestamp of the last record on the stream.
This can be greater than the end position in case of concurrent appends.
Show child attributes
Show child attributes