Reconfigure Stream

curl --request PATCH \
  --url https://api.example.com/streams/{stream}/config \
  --header 'Content-Type: application/json' \
  --data '
{
  "storage_class": "<string>",
  "retention_policy": {},
  "timestamping": {
    "mode": "<string>",
    "uncapped": true
  },
  "delete_on_empty": {
    "min_age_secs": 123
  }
}
'

import requests

url = "https://api.example.com/streams/{stream}/config"

payload = {
    "storage_class": "<string>",
    "retention_policy": {},
    "timestamping": {
        "mode": "<string>",
        "uncapped": True
    },
    "delete_on_empty": { "min_age_secs": 123 }
}
headers = {"Content-Type": "application/json"}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    storage_class: '<string>',
    retention_policy: {},
    timestamping: {mode: '<string>', uncapped: true},
    delete_on_empty: {min_age_secs: 123}
  })
};

fetch('https://api.example.com/streams/{stream}/config', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/streams/{stream}/config",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'storage_class' => '<string>',
    'retention_policy' => [
        
    ],
    'timestamping' => [
        'mode' => '<string>',
        'uncapped' => true
    ],
    'delete_on_empty' => [
        'min_age_secs' => 123
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/streams/{stream}/config"

	payload := strings.NewReader("{\n  \"storage_class\": \"<string>\",\n  \"retention_policy\": {},\n  \"timestamping\": {\n    \"mode\": \"<string>\",\n    \"uncapped\": true\n  },\n  \"delete_on_empty\": {\n    \"min_age_secs\": 123\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.example.com/streams/{stream}/config")
  .header("Content-Type", "application/json")
  .body("{\n  \"storage_class\": \"<string>\",\n  \"retention_policy\": {},\n  \"timestamping\": {\n    \"mode\": \"<string>\",\n    \"uncapped\": true\n  },\n  \"delete_on_empty\": {\n    \"min_age_secs\": 123\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/streams/{stream}/config")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"storage_class\": \"<string>\",\n  \"retention_policy\": {},\n  \"timestamping\": {\n    \"mode\": \"<string>\",\n    \"uncapped\": true\n  },\n  \"delete_on_empty\": {\n    \"min_age_secs\": 123\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "storage_class": "<string>",
  "retention_policy": {},
  "timestamping": {},
  "delete_on_empty": {}
}

PATCH

streams

{stream}

config

Reconfigure Stream

curl --request PATCH \
  --url https://api.example.com/streams/{stream}/config \
  --header 'Content-Type: application/json' \
  --data '
{
  "storage_class": "<string>",
  "retention_policy": {},
  "timestamping": {
    "mode": "<string>",
    "uncapped": true
  },
  "delete_on_empty": {
    "min_age_secs": 123
  }
}
'

import requests

url = "https://api.example.com/streams/{stream}/config"

payload = {
    "storage_class": "<string>",
    "retention_policy": {},
    "timestamping": {
        "mode": "<string>",
        "uncapped": True
    },
    "delete_on_empty": { "min_age_secs": 123 }
}
headers = {"Content-Type": "application/json"}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    storage_class: '<string>',
    retention_policy: {},
    timestamping: {mode: '<string>', uncapped: true},
    delete_on_empty: {min_age_secs: 123}
  })
};

fetch('https://api.example.com/streams/{stream}/config', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/streams/{stream}/config",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'storage_class' => '<string>',
    'retention_policy' => [
        
    ],
    'timestamping' => [
        'mode' => '<string>',
        'uncapped' => true
    ],
    'delete_on_empty' => [
        'min_age_secs' => 123
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/streams/{stream}/config"

	payload := strings.NewReader("{\n  \"storage_class\": \"<string>\",\n  \"retention_policy\": {},\n  \"timestamping\": {\n    \"mode\": \"<string>\",\n    \"uncapped\": true\n  },\n  \"delete_on_empty\": {\n    \"min_age_secs\": 123\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.example.com/streams/{stream}/config")
  .header("Content-Type", "application/json")
  .body("{\n  \"storage_class\": \"<string>\",\n  \"retention_policy\": {},\n  \"timestamping\": {\n    \"mode\": \"<string>\",\n    \"uncapped\": true\n  },\n  \"delete_on_empty\": {\n    \"min_age_secs\": 123\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/streams/{stream}/config")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"storage_class\": \"<string>\",\n  \"retention_policy\": {},\n  \"timestamping\": {\n    \"mode\": \"<string>\",\n    \"uncapped\": true\n  },\n  \"delete_on_empty\": {\n    \"min_age_secs\": 123\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "storage_class": "<string>",
  "retention_policy": {},
  "timestamping": {},
  "delete_on_empty": {}
}

Overview

Update the configuration of an existing stream. Only the specified fields will be updated; unspecified fields remain unchanged. This endpoint uses PATCH semantics, meaning you only need to include the fields you want to change.

Authentication

This endpoint requires authentication via the S2-Basin header containing your basin name.

Path Parameters

string

required

The name of the stream to reconfigure.Example: logs/application

Request Body

All fields are optional. Include only the fields you want to update.

string

Update the storage class:

standard - Append tail latency under 400ms
express - Append tail latency under 40ms

object

Update the retention policy.Options:

{"age": <seconds>} - Age in seconds for automatic trimming (must be > 0)
{"infinite": {}} - Retain records unless explicitly trimmed

object

Update timestamping behavior. You can update individual fields within this object.

Show TimestampingReconfiguration

string

Update timestamping mode:

client-prefer - Prefer client timestamp if present, otherwise use arrival time
client-require - Require client timestamp, reject if missing
arrival - Use arrival time, ignore client timestamp

boolean

Update whether client timestamps can exceed arrival time.

object

Update automatic deletion configuration.

Show DeleteOnEmptyReconfiguration

number

Update minimum age in seconds before an empty stream can be deleted. Set to 0 to disable.

Response

Returns the complete updated stream configuration.

string

Current storage class.

object

Current retention policy.

object

Current timestamping configuration.

object

Current delete-on-empty configuration.

Example Requests

Update Storage Class Only

cURL

curl -X PATCH 'https://{basin}.b.aws.s2.dev/v1/streams/logs%2Fapplication/config' \
  -H 'S2-Basin: my-basin' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "storage_class": "express"
  }'

Update Retention Policy

cURL

curl -X PATCH 'https://{basin}.b.aws.s2.dev/v1/streams/logs%2Fapplication/config' \
  -H 'S2-Basin: my-basin' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "retention_policy": {
      "age": 2592000
    }
  }'

Update Multiple Settings

cURL

curl -X PATCH 'https://{basin}.b.aws.s2.dev/v1/streams/logs%2Fapplication/config' \
  -H 'S2-Basin: my-basin' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "storage_class": "express",
    "timestamping": {
      "mode": "arrival"
    },
    "delete_on_empty": {
      "min_age_secs": 3600
    }
  }'

Stream names in the URL must be properly URL-encoded. For example, logs/application becomes logs%2Fapplication.

Example Response

{
  "storage_class": "express",
  "retention_policy": {
    "age": 2592000
  },
  "timestamping": {
    "mode": "arrival",
    "uncapped": false
  },
  "delete_on_empty": {
    "min_age_secs": 3600
  }
}

Error Responses

404 Not Found - Stream does not exist
400 Bad Request - Invalid configuration (e.g., retention age of 0)
403 Forbidden - Insufficient permissions to reconfigure the stream
409 Conflict - Configuration conflict

Overview

Basins

Streams

Records

Access Tokens

Metrics

Reconfigure Stream

Overview

Authentication

Path Parameters

Request Body

Response

Example Requests

Update Storage Class Only

Update Retention Policy

Update Multiple Settings

Example Response

Error Responses

​Overview

​Authentication

​Path Parameters

​Request Body

​Response

​Example Requests

​Update Storage Class Only

​Update Retention Policy

​Update Multiple Settings

​Example Response

​Error Responses

Overview

Authentication

Path Parameters

Request Body

Response

Example Requests

Update Storage Class Only

Update Retention Policy

Update Multiple Settings

Example Response

Error Responses