Create Stream

curl --request POST \
  --url https://api.example.com/streams \
  --header 'Content-Type: application/json' \
  --data '
{
  "stream": "<string>",
  "config": {
    "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"

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

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

print(response.text)

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

fetch('https://api.example.com/streams', 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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'stream' => '<string>',
    'config' => [
        '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"

	payload := strings.NewReader("{\n  \"stream\": \"<string>\",\n  \"config\": {\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  }\n}")

	req, _ := http.NewRequest("POST", 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.post("https://api.example.com/streams")
  .header("Content-Type", "application/json")
  .body("{\n  \"stream\": \"<string>\",\n  \"config\": {\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  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/streams")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"stream\": \"<string>\",\n  \"config\": {\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  }\n}"

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

{
  "name": "<string>",
  "created_at": "<string>",
  "deleted_at": {}
}

POST

streams

Create Stream

curl --request POST \
  --url https://api.example.com/streams \
  --header 'Content-Type: application/json' \
  --data '
{
  "stream": "<string>",
  "config": {
    "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"

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

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

print(response.text)

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

fetch('https://api.example.com/streams', 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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'stream' => '<string>',
    'config' => [
        '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"

	payload := strings.NewReader("{\n  \"stream\": \"<string>\",\n  \"config\": {\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  }\n}")

	req, _ := http.NewRequest("POST", 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.post("https://api.example.com/streams")
  .header("Content-Type", "application/json")
  .body("{\n  \"stream\": \"<string>\",\n  \"config\": {\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  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/streams")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"stream\": \"<string>\",\n  \"config\": {\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  }\n}"

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

{
  "name": "<string>",
  "created_at": "<string>",
  "deleted_at": {}
}

Overview

Create a new stream with an optional configuration. The stream name must be unique within the basin.

Authentication

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

Headers

string

Optional idempotency token to ensure the request is processed only once. If a stream with the same name already exists and was created with the same token, returns the existing stream instead of an error.

Request Body

string

required

Stream name that is unique to the basin. Can be between 1 and 512 bytes in length.Example: logs/application, metrics/cpu, events/user-actions

StreamConfig

Optional stream configuration. If not provided, basin defaults will be used.

Show StreamConfig

string

Storage class for recent writes. Options:

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

object

Retention policy for the stream. If unspecified, defaults to 7 days.Options:

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

object

Timestamping behavior configuration.

Show TimestampingConfig

string

Timestamping mode:

client-prefer (default) - 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

default:"false"

Allow client timestamps to exceed arrival time. If false, client timestamps are capped at arrival time.

object

Automatic deletion configuration for empty streams.

Show DeleteOnEmptyConfig

number

default:"0"

Minimum age in seconds before an empty stream can be deleted. Set to 0 to disable automatic deletion.

Response

Returns HTTP 201 Created on success.

string

Stream name.

string

Creation time in RFC 3339 format.

string | null

Always null for newly created streams.

Example Request

cURL

curl -X POST 'https://{basin}.b.aws.s2.dev/v1/streams' \
  -H 'S2-Basin: my-basin' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "stream": "logs/application",
    "config": {
      "storage_class": "standard",
      "retention_policy": {
        "age": 604800
      },
      "timestamping": {
        "mode": "client-prefer",
        "uncapped": false
      }
    }
  }'

Example Response

{
  "name": "logs/application",
  "created_at": "2024-01-15T10:30:00Z",
  "deleted_at": null
}

Error Responses

409 Conflict - Stream with this name already exists
400 Bad Request - Invalid stream name or configuration
404 Not Found - Basin does not exist

Overview

Basins

Streams

Records

Access Tokens

Metrics

Create Stream

Overview

Authentication

Headers

Request Body

Response

Example Request

Example Response

Error Responses

​Overview

​Authentication

​Headers

​Request Body

​Response

​Example Request

​Example Response

​Error Responses

Overview

Authentication

Headers

Request Body

Response

Example Request

Example Response

Error Responses