Skip to main content
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
    }
  }
}
'
{
  "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

​
S2-Request-Token
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

​
stream
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
​
config
StreamConfig
Optional stream configuration. If not provided, basin defaults will be used.

​
Response

Returns HTTP 201 Created on success.
​
name
string
Stream name.
​
created_at
string
Creation time in RFC 3339 format.
​
deleted_at
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

Build docs developers (and LLMs) love

Get started for freeTalk to us