Amazon S3 Tables API

openapi: 3.1.0
info:
  title: Amazon S3 Control Access Control Tables API
  description: Amazon S3 Control provides API operations for managing S3 account-level settings, access points, Batch Operations jobs, S3 Access Grants, Multi-Region Access Points, and Storage Lens configurations. The S3 Control API uses a separate endpoint from the standard S3 API and requires an account ID in the host header.
  version: '2018-08-20'
  contact:
    name: AWS Support
    url: https://aws.amazon.com/premiumsupport/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: https://aws.amazon.com/service-terms/
  x-logo:
    url: https://a0.awsstatic.com/libra-css/images/logos/aws_logo_smile_1200x630.png
servers:
- url: https://s3-control.{region}.amazonaws.com
  description: Amazon S3 Control regional endpoint
  variables:
    region:
      default: us-east-1
      description: AWS region
      enum:
      - us-east-1
      - us-east-2
      - us-west-1
      - us-west-2
      - eu-west-1
      - eu-west-2
      - eu-west-3
      - eu-central-1
      - eu-north-1
      - ap-northeast-1
      - ap-northeast-2
      - ap-southeast-1
      - ap-southeast-2
      - ap-south-1
      - sa-east-1
      - ca-central-1
security:
- sigv4: []
tags:
- name: Tables
  description: Operations for creating and managing tables within table buckets
paths:
  /tables/{tableBucketARN}/{namespace}:
    get:
      operationId: ListTables
      summary: Amazon S3 List Tables
      description: Lists the tables in the specified namespace within a table bucket.
      tags:
      - Tables
      parameters:
      - $ref: '#/components/parameters/TableBucketARN'
      - $ref: '#/components/parameters/Namespace'
      - name: prefix
        in: query
        description: The prefix of the table names.
        schema:
          type: string
        example: example_value
      - name: continuationToken
        in: query
        description: A continuation token for pagination.
        schema:
          type: string
        example: example_value
      - name: maxTables
        in: query
        description: The maximum number of tables to return.
        schema:
          type: integer
          minimum: 1
          maximum: 1000
        example: 10
      responses:
        '200':
          description: Successfully returned list of tables.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTablesResponse'
              examples:
                Listtables200Example:
                  summary: Default ListTables 200 response
                  x-microcks-default: true
                  value:
                    tables:
                    - namespace: {}
                      name: Example Title
                      type: customer
                      tableARN: example_value
                      createdAt: '2026-01-15T10:30:00Z'
                      modifiedAt: '2026-01-15T10:30:00Z'
                    continuationToken: example_value
        '404':
          description: The specified namespace does not exist.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: CreateTable
      summary: Amazon S3 Create Table
      description: Creates a new table in the specified namespace within a table bucket. The table is created in Apache Iceberg format and data is stored in Apache Parquet format.
      tags:
      - Tables
      parameters:
      - $ref: '#/components/parameters/TableBucketARN'
      - $ref: '#/components/parameters/Namespace'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTableRequest'
            examples:
              CreatetableRequestExample:
                summary: Default CreateTable request
                x-microcks-default: true
                value:
                  name: Example Title
                  format: ICEBERG
      responses:
        '200':
          description: Table created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  tableARN:
                    type: string
                    description: The Amazon Resource Name (ARN) of the table.
                  versionToken:
                    type: string
                    description: The version token for the table.
              examples:
                Createtable200Example:
                  summary: Default CreateTable 200 response
                  x-microcks-default: true
                  value:
                    tableARN: example_value
                    versionToken: example_value
        '409':
          description: A table with this name already exists.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /tables/{tableBucketARN}/{namespace}/{name}:
    get:
      operationId: GetTable
      summary: Amazon S3 Get Table
      description: Gets details about a table in the specified namespace within a table bucket.
      tags:
      - Tables
      parameters:
      - $ref: '#/components/parameters/TableBucketARN'
      - $ref: '#/components/parameters/Namespace'
      - name: name
        in: path
        required: true
        description: The name of the table.
        schema:
          type: string
        example: Example Title
      responses:
        '200':
          description: Successfully returned table details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TableDetail'
              examples:
                Gettable200Example:
                  summary: Default GetTable 200 response
                  x-microcks-default: true
                  value:
                    name: Example Title
                    tableARN: example_value
                    namespace:
                    - example_value
                    versionToken: example_value
                    metadataLocation: example_value
                    warehouseLocation: example_value
                    createdAt: '2026-01-15T10:30:00Z'
                    createdBy: example_value
                    modifiedAt: '2026-01-15T10:30:00Z'
                    modifiedBy: example_value
                    managedByService: example_value
                    ownerAccountId: '500123'
                    type: customer
                    format: ICEBERG
        '404':
          description: The specified table does not exist.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: DeleteTable
      summary: Amazon S3 Delete Table
      description: Deletes a table from the specified namespace within a table bucket.
      tags:
      - Tables
      parameters:
      - $ref: '#/components/parameters/TableBucketARN'
      - $ref: '#/components/parameters/Namespace'
      - name: name
        in: path
        required: true
        description: The name of the table to delete.
        schema:
          type: string
        example: Example Title
      - name: versionToken
        in: query
        description: The version token of the table.
        schema:
          type: string
        example: example_value
      responses:
        '204':
          description: Table deleted successfully.
        '404':
          description: The specified table does not exist.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: RenameTable
      summary: Amazon S3 Rename Table
      description: Renames a table or moves a table to a different namespace within a table bucket.
      tags:
      - Tables
      parameters:
      - $ref: '#/components/parameters/TableBucketARN'
      - $ref: '#/components/parameters/Namespace'
      - name: name
        in: path
        required: true
        description: The current name of the table.
        schema:
          type: string
        example: Example Title
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                versionToken:
                  type: string
                  description: The version token of the table.
                newNamespaceName:
                  type: string
                  description: The new namespace for the table. If not specified, the table stays in the current namespace.
                newName:
                  type: string
                  description: The new name for the table.
            examples:
              RenametableRequestExample:
                summary: Default RenameTable request
                x-microcks-default: true
                value:
                  versionToken: example_value
                  newNamespaceName: example_value
                  newName: example_value
      responses:
        '200':
          description: Table renamed successfully.
        '404':
          description: The specified table does not exist.
        '409':
          description: A table with the new name already exists.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /tables/{tableBucketARN}/{namespace}/{name}/metadata-location:
    get:
      operationId: GetTableMetadataLocation
      summary: Amazon S3 Get Table Metadata Location
      description: Gets the location of the table metadata in S3.
      tags:
      - Tables
      parameters:
      - $ref: '#/components/parameters/TableBucketARN'
      - $ref: '#/components/parameters/Namespace'
      - name: name
        in: path
        required: true
        description: The name of the table.
        schema:
          type: string
        example: Example Title
      responses:
        '200':
          description: Successfully returned table metadata location.
          content:
            application/json:
              schema:
                type: object
                properties:
                  versionToken:
                    type: string
                  metadataLocation:
                    type: string
                    description: The S3 URI of the table metadata file.
                  warehouseLocation:
                    type: string
                    description: The S3 URI of the warehouse location.
              examples:
                Gettablemetadatalocation200Example:
                  summary: Default GetTableMetadataLocation 200 response
                  x-microcks-default: true
                  value:
                    versionToken: example_value
                    metadataLocation: example_value
                    warehouseLocation: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: UpdateTableMetadataLocation
      summary: Amazon S3 Update Table Metadata Location
      description: Updates the metadata location for a table. Used to point the table to a new Iceberg metadata file after a metadata update.
      tags:
      - Tables
      parameters:
      - $ref: '#/components/parameters/TableBucketARN'
      - $ref: '#/components/parameters/Namespace'
      - name: name
        in: path
        required: true
        description: The name of the table.
        schema:
          type: string
        example: Example Title
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - versionToken
              - metadataLocation
              properties:
                versionToken:
                  type: string
                  description: The version token of the table.
                metadataLocation:
                  type: string
                  description: The new S3 URI for the table metadata file.
            examples:
              UpdatetablemetadatalocationRequestExample:
                summary: Default UpdateTableMetadataLocation request
                x-microcks-default: true
                value:
                  versionToken: example_value
                  metadataLocation: example_value
      responses:
        '200':
          description: Table metadata location updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                  tableARN:
                    type: string
                  versionToken:
                    type: string
                  metadataLocation:
                    type: string
              examples:
                Updatetablemetadatalocation200Example:
                  summary: Default UpdateTableMetadataLocation 200 response
                  x-microcks-default: true
                  value:
                    name: Example Title
                    tableARN: example_value
                    versionToken: example_value
                    metadataLocation: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    TableBucketARN:
      name: tableBucketARN
      in: path
      required: true
      description: The Amazon Resource Name (ARN) of the table bucket.
      schema:
        type: string
    Namespace:
      name: namespace
      in: path
      required: true
      description: The name of the namespace.
      schema:
        type: string
  schemas:
    TableDetail:
      type: object
      properties:
        name:
          type: string
          description: The name of the table.
          example: Example Title
        tableARN:
          type: string
          description: The Amazon Resource Name (ARN) of the table.
          example: example_value
        namespace:
          type: array
          items:
            type: string
          example: []
        versionToken:
          type: string
          description: The version token of the table.
          example: example_value
        metadataLocation:
          type: string
          description: The S3 URI location of the table metadata.
          example: example_value
        warehouseLocation:
          type: string
          description: The S3 URI of the warehouse location for the table.
          example: example_value
        createdAt:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
        createdBy:
          type: string
          example: example_value
        modifiedAt:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
        modifiedBy:
          type: string
          example: example_value
        managedByService:
          type: string
          example: example_value
        ownerAccountId:
          type: string
          example: '500123'
        type:
          type: string
          enum:
          - customer
          - aws
          example: customer
        format:
          type: string
          enum:
          - ICEBERG
          example: ICEBERG
    CreateTableRequest:
      type: object
      required:
      - name
      - format
      properties:
        name:
          type: string
          description: The name for the table.
          minLength: 1
          maxLength: 255
          example: Example Title
        format:
          type: string
          description: The format of the table. Currently only ICEBERG is supported.
          enum:
          - ICEBERG
          example: ICEBERG
    TableSummary:
      type: object
      properties:
        namespace:
          type: array
          items:
            type: string
          example: []
        name:
          type: string
          description: The name of the table.
          example: Example Title
        type:
          type: string
          description: The type of the table.
          enum:
          - customer
          - aws
          example: customer
        tableARN:
          type: string
          description: The Amazon Resource Name (ARN) of the table.
          example: example_value
        createdAt:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
        modifiedAt:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
    ListTablesResponse:
      type: object
      properties:
        tables:
          type: array
          items:
            $ref: '#/components/schemas/TableSummary'
          example: []
        continuationToken:
          type: string
          example: example_value
  securitySchemes:
    sigv4:
      type: apiKey
      name: Authorization
      in: header
      description: AWS Signature Version 4 authentication. The S3 Control API uses the service name s3 for signing.
externalDocs:
  description: Amazon S3 Control API Reference
  url: https://docs.aws.amazon.com/AmazonS3/latest/API/API_Types_AWS_S3_Control.html