> ## Documentation Index
> Fetch the complete documentation index at: https://s2.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> Create a new S2 stream in a basin.

# Create a stream.

<Note>
  Stream encryption is not configured explicitly when creating a stream. A stream inherits the basin's configured `stream_cipher` when it is created, and that cipher is immutable for the lifetime of the stream.
</Note>


## OpenAPI

````yaml post /streams
openapi: 3.1.0
info:
  title: S2, the durable streams API
  description: Streams as a cloud storage primitive.
  termsOfService: https://s2.dev/terms
  contact:
    email: support@s2.dev
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://aws.s2.dev/v1
security:
  - access_token: []
tags:
  - name: metrics
    description: Usage metrics and data.
  - name: basins
    description: Manage basins
  - name: access-tokens
    description: Manage access tokens
  - name: locations
    description: Manage locations
  - name: streams
    description: Manage streams
  - name: records
    description: Manage records
paths:
  /streams:
    servers:
      - url: https://{basin}.b.s2.dev/v1
        description: Endpoint for the basin
        variables:
          basin:
            default: ''
            description: Basin name
    post:
      tags:
        - streams
      summary: Create a stream.
      operationId: create_stream
      parameters:
        - name: s2-request-token
          in: header
          description: Client-specified request token for idempotent retries.
          required: false
          schema:
            $ref: '#/components/schemas/RequestToken'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateStreamRequest'
        required: true
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StreamInfo'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
        '408':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
components:
  schemas:
    RequestToken:
      type: string
      maxLength: 36
    CreateStreamRequest:
      type: object
      required:
        - stream
      properties:
        config:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/StreamConfig'
              description: Stream configuration.
        stream:
          $ref: '#/components/schemas/StreamNameStr'
          description: |-
            Stream name that is unique to the basin.
            It can be between 1 and 512 bytes in length.
    StreamInfo:
      type: object
      required:
        - name
        - created_at
      properties:
        cipher:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/EncryptionAlgorithm'
              description: Encryption algorithm for this stream, if encryption is enabled.
        created_at:
          type: string
          format: date-time
          description: Creation time in RFC 3339 format.
        deleted_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Deletion time in RFC 3339 format, if the stream is being deleted.
        name:
          $ref: '#/components/schemas/StreamNameStr'
          description: Stream name.
    ErrorInfo:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
    StreamConfig:
      type: object
      properties:
        delete_on_empty:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/DeleteOnEmptyConfig'
              description: Delete-on-empty configuration.
        retention_policy:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/RetentionPolicy'
              description: |-
                Retention policy for the stream.
                If unspecified, the default is to retain records for 7 days.
        storage_class:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/StorageClass'
              description: Storage class for recent writes.
        timestamping:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/TimestampingConfig'
              description: Timestamping behavior.
    StreamNameStr:
      type: string
      maxLength: 512
      minLength: 1
    EncryptionAlgorithm:
      type: string
      enum:
        - aegis-256
        - aes-256-gcm
    DeleteOnEmptyConfig:
      type: object
      properties:
        min_age_secs:
          type: integer
          format: int64
          description: >-
            Minimum age in seconds before an empty stream can be deleted.

            Set to 0 (default) to disable delete-on-empty (don't delete
            automatically).
          minimum: 0
    RetentionPolicy:
      oneOf:
        - type: object
          description: >-
            Age in seconds for automatic trimming of records older than this
            threshold.

            This must be set to a value greater than 0 seconds.
          required:
            - age
          properties:
            age:
              type: integer
              format: int64
              description: >-
                Age in seconds for automatic trimming of records older than this
                threshold.

                This must be set to a value greater than 0 seconds.
              minimum: 0
        - type: object
          description: Retain records unless explicitly trimmed.
          required:
            - infinite
          properties:
            infinite:
              $ref: '#/components/schemas/InfiniteRetention'
              description: Retain records unless explicitly trimmed.
    StorageClass:
      type: string
      enum:
        - standard
        - express
    TimestampingConfig:
      type: object
      properties:
        mode:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/TimestampingMode'
              description: >-
                Timestamping mode for appends that influences how timestamps are
                handled.
        uncapped:
          type:
            - boolean
            - 'null'
          description: >-
            Allow client-specified timestamps to exceed the arrival time.

            If this is `false` or not set, client timestamps will be capped at
            the arrival time.
    InfiniteRetention:
      type: object
    TimestampingMode:
      type: string
      enum:
        - client-prefer
        - client-require
        - arrival
  securitySchemes:
    access_token:
      type: http
      scheme: bearer
      description: >-
        Bearer authentication header of the form `Bearer <token>`, where
        `<token>` is your access token.

````