Skip to main content
POST
/
streams
/
{stream}
/
records
Append records.
curl --request POST \
  --url https://{basin}.b.aws.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
  }
}
Appends execute atomically — either all the records in a batch will become durable, or none. S2 returns the range of sequence numbers assigned, the timestamps of the first and last record, and the current tail. With an AppendSession (available via SDKs), you can pipeline batches with an ordering guarantee, and receive acknowledgements back in the corresponding order. If any batch fails, subsequent batches will not become durable.
depends on the storage class for the stream. A Standard stream will ack writes within 400 milliseconds, and an Express stream within 40 milliseconds.

​
Concurrency control

Appends support match_seq_num (optimistic) and fencing_token (pessimistic) concurrency controls. If the condition is not met, the append will result in a 412 Precondition Failed status or corresponding SDK error type.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your access token.

Headers

​
s2-format
enum<string>

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

Path Parameters

​
stream
string
required

Stream name.

Required string length: 1 - 512

Body

application/json

Payload of an append request.

​
records
object[]
required

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.

​
fencing_token
null | string

Enforce a fencing token, which starts out as an empty string that can be overridden by a fence command record.

Maximum string length: 36
​
match_seq_num
null | integer<int64>

Enforce that the sequence number assigned to the first record matches.

Required range: x >= 0

Response

Success response to an append request.

​
end
object
required

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.

​
start
object
required

Sequence number and timestamp of the first record that was appended.

​
tail
object
required

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.