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": null
    }
  ]
}'
{
  "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 most 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.

Acknowledgment latency depends on the storage class for the stream. A Standard stream will acknowledge writes within 500 milliseconds, and an Express stream within 50 milliseconds.

​
Concurrency control

Appends support two mechanisms for concurrency control:

​
Match sequence

Specifying expected current state allows optimistic concurrency control.

You can provide the sequence number that you expect S2 to assign to the first record in a batch as the match_seq_num.

If it does not match, this will result in a 412 Precondition Failed status or corresponding SDK error type.

​
Fencing token

Fencing is a form of pessimistic concurrency control.

It is a cooperative mechanism, so an append that does not specify a fencing token will still be allowed.

When an append does include a fencing_token and it does not match, this results in in a 412 Precondition Failed status or corresponding SDK error type.

Setting the current fencing token itself requires appending to the stream, with the fence command.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth 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.

Body

application/json

Payload of an append request.

Response

200
application/json

Success response to an append request.