Amazon S3 S3 Tables API

openapi: 3.1.0
info:
  title: Amazon Simple Storage Service Tables API
  version: '2006-03-01'
  description: Generated from AWS's published Smithy model for Amazon Simple Storage Service. 3 operation(s).
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/contact-us/
  license:
    name: Apache 2.0
    identifier: Apache-2.0
    url: https://github.com/aws/api-models-aws/blob/main/LICENSE
servers:
- url: https://s3tables.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
paths:
  /tables/{tableBucketARN}/{namespace}:
    put:
      operationId: CreateTable
      summary: Create Table
      description: Creates a new table associated with the given namespace in a table bucket. For more information, see Creating
        an Amazon S3 table in the Amazon Simple Storage Service User Guide. Permissions You must have the s3tables:CreateTable
        permission to use this operation. If you use this operation with the optional metadata request parameter you must
        have the s3tables:PutTableData permission. If you use this operation with the optional encryptionConfiguration request
        parameter you must have the s3tables:PutTableEncryption permission. If you use this operation with the storageClassConfiguration
        request parameter, you must have the s3tables:PutTableStorageClass permission. To create a table with tags, you must
        have the s3tables:TagResource permission in addition to s3tables:CreateTable permission. Additionally, If you choose
        SSE-KMS encryption you must grant the S3 Tables maintenance principal access to your KMS key. For more information,
        see Permissions requirements for S3 Tables SSE-KMS encryption.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTableResponse'
        '400':
          description: BadRequestException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/S3TablesBadRequestException'
        '409':
          description: ConflictException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictException'
        '403':
          description: ForbiddenException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenException'
        '500':
          description: InternalServerErrorException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorException'
        '404':
          description: NotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/S3TablesNotFoundException'
        '429':
          description: TooManyRequestsException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTableRequest'
      tags:
      - Tables
  /tables/{tableBucketARN}/{namespace}/{name}:
    delete:
      operationId: DeleteTable
      summary: Delete Table
      description: Deletes a table. For more information, see Deleting an Amazon S3 table in the Amazon Simple Storage Service
        User Guide. Permissions You must have the s3tables:DeleteTable permission to use this operation.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: string
        '400':
          description: BadRequestException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/S3TablesBadRequestException'
        '409':
          description: ConflictException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictException'
        '403':
          description: ForbiddenException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenException'
        '500':
          description: InternalServerErrorException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorException'
        '404':
          description: NotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/S3TablesNotFoundException'
        '429':
          description: TooManyRequestsException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteTableRequest'
      tags:
      - Tables
  /tables/{tableBucketARN}:
    get:
      operationId: ListTables
      summary: List Tables
      description: List tables in the given table bucket. For more information, see S3 Tables in the Amazon Simple Storage
        Service User Guide. Permissions You must have the s3tables:ListTables permission to use this operation.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTablesResponse'
        '400':
          description: BadRequestException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/S3TablesBadRequestException'
        '409':
          description: ConflictException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictException'
        '403':
          description: ForbiddenException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenException'
        '500':
          description: InternalServerErrorException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorException'
        '404':
          description: NotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/S3TablesNotFoundException'
        '429':
          description: TooManyRequestsException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListTablesRequest'
      tags:
      - Tables
components:
  securitySchemes:
    sigv4:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4. The Authorization header carries an AWS4-HMAC-SHA256 signature over the canonical
        request, with X-Amz-Date (and X-Amz-Security-Token for temporary credentials). Not a bearer token.
      x-aws-sigv4:
        signingName: s3tables
  schemas:
    ConflictException:
      type: object
      properties:
        message:
          type: string
    CreateTableRequest:
      type: object
      properties:
        tableBucketARN:
          type: string
          description: The Amazon Resource Name (ARN) of the table bucket to create the table in.
        namespace:
          type: string
          description: The namespace to associated with the table.
        name:
          type: string
          description: The name for the table.
        format:
          type: string
          enum:
          - ICEBERG
          description: The format for the table.
        metadata:
          $ref: '#/components/schemas/TableMetadata'
        encryptionConfiguration:
          $ref: '#/components/schemas/S3TablesEncryptionConfiguration'
        storageClassConfiguration:
          $ref: '#/components/schemas/StorageClassConfiguration'
        tags:
          type: object
          additionalProperties:
            type: string
          description: A map of user-defined tags that you would like to apply to the table that you are creating. A tag is
            a key-value pair that you apply to your resources. Tags can help you organize, track costs for, and control access
            to resources. For more information, see Tagging for cost allocation or attribute-based access control (ABAC).
            You must have the s3tables:TagResource permission in addition to s3tables:CreateTable permission to create a table
            with tags.
      required:
      - tableBucketARN
      - namespace
      - name
      - format
    CreateTableResponse:
      type: object
      properties:
        tableARN:
          type: string
          description: The Amazon Resource Name (ARN) of the table.
        versionToken:
          type: string
          description: The version token of the table.
      required:
      - tableARN
      - versionToken
    DeleteTableRequest:
      type: object
      properties:
        tableBucketARN:
          type: string
          description: The Amazon Resource Name (ARN) of the table bucket that contains the table.
        namespace:
          type: string
          description: The namespace associated with the table.
        name:
          type: string
          description: The name of the table.
        versionToken:
          type: string
          description: The version token of the table.
      required:
      - tableBucketARN
      - namespace
      - name
    ForbiddenException:
      type: object
      properties:
        message:
          type: string
    IcebergMetadata:
      type: object
      properties:
        schema:
          $ref: '#/components/schemas/IcebergSchema'
        schemaV2:
          $ref: '#/components/schemas/IcebergSchemaV2'
        partitionSpec:
          $ref: '#/components/schemas/IcebergPartitionSpec'
        writeOrder:
          $ref: '#/components/schemas/IcebergSortOrder'
        properties:
          type: object
          additionalProperties:
            type: string
          description: A map of custom configuration properties for the Iceberg table.
    IcebergPartitionField:
      type: object
      properties:
        sourceId:
          type: integer
          description: The ID of the source schema field to partition by. This must reference a valid field ID from the table
            schema.
        transform:
          type: string
          description: The partition transform to apply to the source field. Supported transforms include identity, year,
            month, day, hour, bucket, and truncate. For more information, see the Apache Iceberg partition transforms documentation.
        name:
          type: string
          description: The name for this partition field. This name is used in the partitioned file paths.
        fieldId:
          type: integer
          description: An optional unique identifier for this partition field. If not specified, S3 Tables automatically assigns
            a field ID.
      required:
      - sourceId
      - transform
      - name
    IcebergPartitionSpec:
      type: object
      properties:
        fields:
          type: array
          items:
            $ref: '#/components/schemas/IcebergPartitionField'
          description: The list of partition fields that define how the table data is partitioned. Each field specifies a
            source field and a transform to apply. This field is required if partitionSpec is provided.
        specId:
          type: integer
          description: The unique identifier for this partition specification. If not specified, defaults to 0.
      required:
      - fields
    IcebergSchema:
      type: object
      properties:
        fields:
          type: array
          items:
            $ref: '#/components/schemas/SchemaField'
          description: The schema fields for the table
      required:
      - fields
    IcebergSchemaV2:
      type: object
      properties:
        type:
          type: string
          enum:
          - struct
          description: The type of the top-level schema, which is always a struct type as defined in the Apache Iceberg specification.
            This value must be struct.
        fields:
          type: array
          items:
            $ref: '#/components/schemas/SchemaV2Field'
          description: The schema fields for the table. Each field defines a column in the table, including its name, type,
            and whether it is required.
        schemaId:
          type: integer
          description: An optional unique identifier for the schema. Schema IDs are used by Apache Iceberg to track schema
            evolution.
        identifierFieldIds:
          type: array
          items:
            type: integer
          description: A list of field IDs that are used as the identifier fields for the table. Identifier fields uniquely
            identify a row in the table.
      required:
      - type
      - fields
    IcebergSortField:
      type: object
      properties:
        sourceId:
          type: integer
          description: The ID of the source schema field to sort by. This must reference a valid field ID from the table schema.
        transform:
          type: string
          description: The transform to apply to the source field before sorting. Use identity to sort by the field value
            directly, or specify other transforms as needed.
        direction:
          type: string
          enum:
          - asc
          - desc
          description: The sort direction. Valid values are asc for ascending order or desc for descending order.
        nullOrder:
          type: string
          enum:
          - nulls-first
          - nulls-last
          description: Specifies how null values are ordered. Valid values are nulls-first to place nulls before non-null
            values, or nulls-last to place nulls after non-null values.
      required:
      - sourceId
      - transform
      - direction
      - nullOrder
    IcebergSortOrder:
      type: object
      properties:
        orderId:
          type: integer
          description: The unique identifier for this sort order. If not specified, defaults to 1. The order ID is used by
            Apache Iceberg to track sort order evolution.
        fields:
          type: array
          items:
            $ref: '#/components/schemas/IcebergSortField'
          description: The list of sort fields that define how data is sorted within files. Each field specifies a source
            field, sort direction, and null ordering. This field is required if writeOrder is provided.
      required:
      - orderId
      - fields
    InternalServerErrorException:
      type: object
      properties:
        message:
          type: string
    ListTablesRequest:
      type: object
      properties:
        tableBucketARN:
          type: string
          description: The Amazon resource Name (ARN) of the table bucket.
        namespace:
          type: string
          description: The namespace of the tables.
        prefix:
          type: string
          description: The prefix of the tables.
        continuationToken:
          type: string
          description: ContinuationToken indicates to Amazon S3 that the list is being continued on this bucket with a token.
            ContinuationToken is obfuscated and is not a real key. You can use this ContinuationToken for pagination of the
            list results.
        maxTables:
          type: integer
          description: The maximum number of tables to return.
      required:
      - tableBucketARN
    ListTablesResponse:
      type: object
      properties:
        tables:
          type: array
          items:
            $ref: '#/components/schemas/TableSummary'
          description: A list of tables.
        continuationToken:
          type: string
          description: You can use this ContinuationToken for pagination of the list results.
      required:
      - tables
    S3TablesBadRequestException:
      type: object
      properties:
        message:
          type: string
    S3TablesEncryptionConfiguration:
      type: object
      properties:
        sseAlgorithm:
          type: string
          enum:
          - AES256
          - aws:kms
          description: The server-side encryption algorithm to use. Valid values are AES256 for S3-managed encryption keys,
            or aws:kms for Amazon Web Services KMS-managed encryption keys. If you choose SSE-KMS encryption you must grant
            the S3 Tables maintenance principal access to your KMS key. For more information, see Permissions requirements
            for S3 Tables SSE-KMS encryption.
        kmsKeyArn:
          type: string
          description: The Amazon Resource Name (ARN) of the KMS key to use for encryption. This field is required only when
            sseAlgorithm is set to aws:kms.
      required:
      - sseAlgorithm
    S3TablesNotFoundException:
      type: object
      properties:
        message:
          type: string
    SchemaField:
      type: object
      properties:
        id:
          type: integer
          description: An optional unique identifier for the schema field. Field IDs are used by Apache Iceberg to track schema
            evolution and maintain compatibility across schema changes. If not specified, S3 Tables automatically assigns
            field IDs.
        name:
          type: string
          description: The name of the field.
        type:
          type: string
          description: The field type. S3 Tables supports all Apache Iceberg primitive types. For more information, see the
            Apache Iceberg documentation.
        required:
          type: boolean
          description: A Boolean value that specifies whether values are required for each row in this field. By default,
            this is false and null values are allowed in the field. If this is true the field does not allow null values.
      required:
      - name
      - type
    SchemaV2Field:
      type: object
      properties:
        id:
          type: integer
          description: The unique identifier for the schema field. Field IDs are used by Apache Iceberg to track schema evolution
            and maintain compatibility across schema changes.
        name:
          type: string
          description: The name of the field.
        type:
          type: object
          description: The data type of the field. This can be a primitive type string such as boolean, int, long, float,
            double, string, binary, date, timestamp, or timestamptz, or a complex type represented as a JSON object for nested
            types such as struct, list, or map. For more information, see the Apache Iceberg schemas and data types documentation.
        required:
          type: boolean
          description: A Boolean value that specifies whether values are required for each row in this field. If this is true,
            the field does not allow null values.
        doc:
          type: string
          description: An optional description of the field.
      required:
      - id
      - name
      - type
      - required
    StorageClassConfiguration:
      type: object
      properties:
        storageClass:
          type: string
          enum:
          - STANDARD
          - INTELLIGENT_TIERING
          description: The storage class for the table or table bucket. Valid values include storage classes optimized for
            different access patterns and cost profiles.
      required:
      - storageClass
    TableMetadata:
      type: object
      properties:
        iceberg:
          $ref: '#/components/schemas/IcebergMetadata'
      description: Exactly one member is set.
    TableSummary:
      type: object
      properties:
        namespace:
          type: array
          items:
            type: string
          description: The name of the namespace.
        name:
          type: string
          description: The name of the table.
        type:
          type: string
          enum:
          - customer
          - aws
          description: The type of the table.
        tableARN:
          type: string
          description: The Amazon Resource Name (ARN) of the table.
        createdAt:
          type: string
          description: The date and time the table was created at.
        modifiedAt:
          type: string
          description: The date and time the table was last modified at.
        managedByService:
          type: string
          description: The Amazon Web Services service managing this table, if applicable. For example, a replicated table
            is managed by the S3 Tables replication service.
        namespaceId:
          type: string
          description: The unique identifier for the namespace that contains this table.
        tableBucketId:
          type: string
          description: The unique identifier for the table bucket that contains this table.
      required:
      - namespace
      - name
      - type
      - tableARN
      - createdAt
      - modifiedAt
    TooManyRequestsException:
      type: object
      properties:
        message:
          type: string
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/3cd98287b471c106254abd89279cc87308d38bfd/models/s3tables/service/2018-05-10/s3tables-2018-05-10.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)