# SPDX-License-Identifier: CC-BY-NC-SA-4.0
openapi: 3.1.0
info:
  title: The S3 Interface — API Commons profile
  summary: The S3 object-storage contract, as far as adopters can be shown to implement it.
  description: '**This is a convenience, and `s3-model.json` beside it is the artifact of record.** S3
    identifies operations by a query subresource: 99 of 116 operations are distinguished that way, and
    the whole API collapses to 12 method and path pairs. An OpenAPI path cannot carry a query string,
    so each pair keeps one operation and lists the rest in `x-s3-operations`.


    Read the tiers with the cohort in mind: 58 providers claim S3 compatibility and 12 publish a spec
    declaring an S3 operation. This is the thinnest evidence base of any profile in this programme, and
    the profile says so rather than presenting a confident number.


    Derived from botocore''s service-2.json at `aeb03fc4ae530e0b3f47d588b6021581db870c8c` (Apache-2.0).
    Not published by, affiliated with, or endorsed by Amazon Web Services.'
  version: '2006-03-01'
  contact:
    name: API Commons
    url: https://apicommons.org
  license:
    name: CC-BY-NC-SA-4.0
    url: https://creativecommons.org/licenses/by-nc-sa/4.0/
externalDocs:
  description: The profile on API Commons
  url: https://apicommons.org/standards/storage/
servers:
- url: https://{endpoint}
  variables:
    endpoint:
      default: s3.us-east-1.amazonaws.com
      description: Any endpoint implementing this profile.
paths:
  /{Bucket}:
    delete:
      operationId: DeleteBucket
      summary: DELETE /{Bucket}
      description: '**16 S3 operations share this method and path.** They are distinguished by a query
        subresource, which an OpenAPI path cannot express, so `DeleteBucket` stands here and every operation
        on this pair is listed in `x-s3-operations` with its own tier. See `s3-model.json` for the authoritative
        form.'
      x-tier: core
      x-s3-operations:
      - operation: DeleteBucket
        subresource: null
        tier: core
        providers_declaring: 9
      - operation: DeleteBucketAnalyticsConfiguration
        subresource: analytics
        tier: vendor
        providers_declaring: 0
      - operation: DeleteBucketCors
        subresource: cors
        tier: vendor
        providers_declaring: 0
      - operation: DeleteBucketEncryption
        subresource: encryption
        tier: vendor
        providers_declaring: 0
      - operation: DeleteBucketIntelligentTieringConfiguration
        subresource: intelligent-tiering
        tier: vendor
        providers_declaring: 0
      - operation: DeleteBucketInventoryConfiguration
        subresource: inventory
        tier: vendor
        providers_declaring: 0
      - operation: DeleteBucketLifecycle
        subresource: lifecycle
        tier: vendor
        providers_declaring: 0
      - operation: DeleteBucketMetadataConfiguration
        subresource: metadataConfiguration
        tier: vendor
        providers_declaring: 0
      - operation: DeleteBucketMetadataTableConfiguration
        subresource: metadataTable
        tier: vendor
        providers_declaring: 0
      - operation: DeleteBucketMetricsConfiguration
        subresource: metrics
        tier: vendor
        providers_declaring: 0
      - operation: DeleteBucketOwnershipControls
        subresource: ownershipControls
        tier: vendor
        providers_declaring: 0
      - operation: DeleteBucketPolicy
        subresource: policy
        tier: vendor
        providers_declaring: 0
      - operation: DeleteBucketReplication
        subresource: replication
        tier: vendor
        providers_declaring: 0
      - operation: DeleteBucketTagging
        subresource: tagging
        tier: vendor
        providers_declaring: 0
      - operation: DeleteBucketWebsite
        subresource: website
        tier: vendor
        providers_declaring: 0
      - operation: DeletePublicAccessBlock
        subresource: publicAccessBlock
        tier: vendor
        providers_declaring: 0
      parameters:
      - name: subresource
        in: query
        required: false
        description: The subresource selects the operation. Absent means the base operation on this method
          and path.
        schema:
          type: string
          enum:
          - analytics
          - cors
          - encryption
          - intelligent-tiering
          - inventory
          - lifecycle
          - metadataConfiguration
          - metadataTable
          - metrics
          - ownershipControls
          - policy
          - publicAccessBlock
          - replication
          - tagging
          - website
      responses:
        '200':
          description: The operation's XML response. S3 is rest-xml, not JSON.
        '403':
          description: AccessDenied. Note that S3 validates the signature BEFORE routing the operation,
            so this answer does not distinguish an unsupported operation from an unauthorised one.
    get:
      operationId: ListObjects
      summary: GET /{Bucket}
      description: '**36 S3 operations share this method and path.** They are distinguished by a query
        subresource, which an OpenAPI path cannot express, so `ListObjects` stands here and every operation
        on this pair is listed in `x-s3-operations` with its own tier. See `s3-model.json` for the authoritative
        form.'
      x-tier: core
      x-s3-operations:
      - operation: CreateSession
        subresource: session
        tier: vendor
        providers_declaring: 1
      - operation: GetBucketAbac
        subresource: abac
        tier: vendor
        providers_declaring: 0
      - operation: GetBucketAccelerateConfiguration
        subresource: accelerate
        tier: vendor
        providers_declaring: 0
      - operation: GetBucketAcl
        subresource: acl
        tier: vendor
        providers_declaring: 1
      - operation: GetBucketAnalyticsConfiguration
        subresource: analytics
        tier: vendor
        providers_declaring: 0
      - operation: GetBucketCors
        subresource: cors
        tier: vendor
        providers_declaring: 0
      - operation: GetBucketEncryption
        subresource: encryption
        tier: vendor
        providers_declaring: 0
      - operation: GetBucketIntelligentTieringConfiguration
        subresource: intelligent-tiering
        tier: vendor
        providers_declaring: 0
      - operation: GetBucketInventoryConfiguration
        subresource: inventory
        tier: vendor
        providers_declaring: 0
      - operation: GetBucketLifecycle
        subresource: lifecycle
        tier: vendor
        providers_declaring: 0
      - operation: GetBucketLifecycleConfiguration
        subresource: lifecycle
        tier: vendor
        providers_declaring: 0
      - operation: GetBucketLocation
        subresource: location
        tier: vendor
        providers_declaring: 0
      - operation: GetBucketLogging
        subresource: logging
        tier: vendor
        providers_declaring: 0
      - operation: GetBucketMetadataConfiguration
        subresource: metadataConfiguration
        tier: vendor
        providers_declaring: 0
      - operation: GetBucketMetadataTableConfiguration
        subresource: metadataTable
        tier: vendor
        providers_declaring: 0
      - operation: GetBucketMetricsConfiguration
        subresource: metrics
        tier: vendor
        providers_declaring: 0
      - operation: GetBucketNotification
        subresource: notification
        tier: vendor
        providers_declaring: 0
      - operation: GetBucketNotificationConfiguration
        subresource: notification
        tier: vendor
        providers_declaring: 0
      - operation: GetBucketOwnershipControls
        subresource: ownershipControls
        tier: vendor
        providers_declaring: 0
      - operation: GetBucketPolicy
        subresource: policy
        tier: vendor
        providers_declaring: 0
      - operation: GetBucketPolicyStatus
        subresource: policyStatus
        tier: vendor
        providers_declaring: 0
      - operation: GetBucketReplication
        subresource: replication
        tier: vendor
        providers_declaring: 0
      - operation: GetBucketRequestPayment
        subresource: requestPayment
        tier: vendor
        providers_declaring: 0
      - operation: GetBucketTagging
        subresource: tagging
        tier: vendor
        providers_declaring: 0
      - operation: GetBucketVersioning
        subresource: versioning
        tier: vendor
        providers_declaring: 0
      - operation: GetBucketWebsite
        subresource: website
        tier: vendor
        providers_declaring: 0
      - operation: GetObjectLockConfiguration
        subresource: object-lock
        tier: vendor
        providers_declaring: 0
      - operation: GetPublicAccessBlock
        subresource: publicAccessBlock
        tier: vendor
        providers_declaring: 0
      - operation: ListBucketAnalyticsConfigurations
        subresource: analytics
        tier: vendor
        providers_declaring: 0
      - operation: ListBucketIntelligentTieringConfigurations
        subresource: intelligent-tiering
        tier: vendor
        providers_declaring: 0
      - operation: ListBucketInventoryConfigurations
        subresource: inventory
        tier: vendor
        providers_declaring: 0
      - operation: ListBucketMetricsConfigurations
        subresource: metrics
        tier: vendor
        providers_declaring: 0
      - operation: ListMultipartUploads
        subresource: uploads
        tier: extended
        providers_declaring: 3
      - operation: ListObjectVersions
        subresource: versions
        tier: vendor
        providers_declaring: 1
      - operation: ListObjects
        subresource: null
        tier: core
        providers_declaring: 10
      - operation: ListObjectsV2
        subresource: list-type=2
        tier: extended
        providers_declaring: 2
      parameters:
      - name: subresource
        in: query
        required: false
        description: The subresource selects the operation. Absent means the base operation on this method
          and path.
        schema:
          type: string
          enum:
          - abac
          - accelerate
          - acl
          - analytics
          - cors
          - encryption
          - intelligent-tiering
          - inventory
          - lifecycle
          - list-type
          - location
          - logging
          - metadataConfiguration
          - metadataTable
          - metrics
          - notification
          - object-lock
          - ownershipControls
          - policy
          - policyStatus
          - publicAccessBlock
          - replication
          - requestPayment
          - session
          - tagging
          - uploads
          - versioning
          - versions
          - website
      responses:
        '200':
          description: The operation's XML response. S3 is rest-xml, not JSON.
        '403':
          description: AccessDenied. Note that S3 validates the signature BEFORE routing the operation,
            so this answer does not distinguish an unsupported operation from an unauthorised one.
    head:
      operationId: HeadBucket
      summary: HEAD /{Bucket}
      description: '**1 S3 operations share this method and path.** They are distinguished by a query
        subresource, which an OpenAPI path cannot express, so `HeadBucket` stands here and every operation
        on this pair is listed in `x-s3-operations` with its own tier. See `s3-model.json` for the authoritative
        form.'
      x-tier: extended
      x-s3-operations:
      - operation: HeadBucket
        subresource: null
        tier: extended
        providers_declaring: 5
      parameters: []
      responses:
        '200':
          description: The operation's XML response. S3 is rest-xml, not JSON.
        '403':
          description: AccessDenied. Note that S3 validates the signature BEFORE routing the operation,
            so this answer does not distinguish an unsupported operation from an unauthorised one.
    put:
      operationId: CreateBucket
      summary: PUT /{Bucket}
      description: '**27 S3 operations share this method and path.** They are distinguished by a query
        subresource, which an OpenAPI path cannot express, so `CreateBucket` stands here and every operation
        on this pair is listed in `x-s3-operations` with its own tier. See `s3-model.json` for the authoritative
        form.'
      x-tier: core
      x-s3-operations:
      - operation: CreateBucket
        subresource: null
        tier: core
        providers_declaring: 8
      - operation: PutBucketAbac
        subresource: abac
        tier: vendor
        providers_declaring: 0
      - operation: PutBucketAccelerateConfiguration
        subresource: accelerate
        tier: vendor
        providers_declaring: 0
      - operation: PutBucketAcl
        subresource: acl
        tier: vendor
        providers_declaring: 1
      - operation: PutBucketAnalyticsConfiguration
        subresource: analytics
        tier: vendor
        providers_declaring: 0
      - operation: PutBucketCors
        subresource: cors
        tier: vendor
        providers_declaring: 0
      - operation: PutBucketEncryption
        subresource: encryption
        tier: vendor
        providers_declaring: 0
      - operation: PutBucketIntelligentTieringConfiguration
        subresource: intelligent-tiering
        tier: vendor
        providers_declaring: 0
      - operation: PutBucketInventoryConfiguration
        subresource: inventory
        tier: vendor
        providers_declaring: 0
      - operation: PutBucketLifecycle
        subresource: lifecycle
        tier: vendor
        providers_declaring: 0
      - operation: PutBucketLifecycleConfiguration
        subresource: lifecycle
        tier: vendor
        providers_declaring: 0
      - operation: PutBucketLogging
        subresource: logging
        tier: vendor
        providers_declaring: 0
      - operation: PutBucketMetricsConfiguration
        subresource: metrics
        tier: vendor
        providers_declaring: 0
      - operation: PutBucketNotification
        subresource: notification
        tier: vendor
        providers_declaring: 0
      - operation: PutBucketNotificationConfiguration
        subresource: notification
        tier: vendor
        providers_declaring: 0
      - operation: PutBucketOwnershipControls
        subresource: ownershipControls
        tier: vendor
        providers_declaring: 0
      - operation: PutBucketPolicy
        subresource: policy
        tier: vendor
        providers_declaring: 0
      - operation: PutBucketReplication
        subresource: replication
        tier: vendor
        providers_declaring: 0
      - operation: PutBucketRequestPayment
        subresource: requestPayment
        tier: vendor
        providers_declaring: 0
      - operation: PutBucketTagging
        subresource: tagging
        tier: vendor
        providers_declaring: 0
      - operation: PutBucketVersioning
        subresource: versioning
        tier: vendor
        providers_declaring: 0
      - operation: PutBucketWebsite
        subresource: website
        tier: vendor
        providers_declaring: 0
      - operation: PutObjectLockConfiguration
        subresource: object-lock
        tier: vendor
        providers_declaring: 0
      - operation: PutPublicAccessBlock
        subresource: publicAccessBlock
        tier: vendor
        providers_declaring: 0
      - operation: UpdateBucketMetadataAnnotationTableConfiguration
        subresource: metadataAnnotationTable
        tier: vendor
        providers_declaring: 0
      - operation: UpdateBucketMetadataInventoryTableConfiguration
        subresource: metadataInventoryTable
        tier: vendor
        providers_declaring: 0
      - operation: UpdateBucketMetadataJournalTableConfiguration
        subresource: metadataJournalTable
        tier: vendor
        providers_declaring: 0
      parameters:
      - name: subresource
        in: query
        required: false
        description: The subresource selects the operation. Absent means the base operation on this method
          and path.
        schema:
          type: string
          enum:
          - abac
          - accelerate
          - acl
          - analytics
          - cors
          - encryption
          - intelligent-tiering
          - inventory
          - lifecycle
          - logging
          - metadataAnnotationTable
          - metadataInventoryTable
          - metadataJournalTable
          - metrics
          - notification
          - object-lock
          - ownershipControls
          - policy
          - publicAccessBlock
          - replication
          - requestPayment
          - tagging
          - versioning
          - website
      responses:
        '200':
          description: The operation's XML response. S3 is rest-xml, not JSON.
        '403':
          description: AccessDenied. Note that S3 validates the signature BEFORE routing the operation,
            so this answer does not distinguish an unsupported operation from an unauthorised one.
  /{Bucket}/{Key+}:
    delete:
      operationId: DeleteObject
      summary: DELETE /{Bucket}/{Key+}
      description: '**4 S3 operations share this method and path.** They are distinguished by a query
        subresource, which an OpenAPI path cannot express, so `DeleteObject` stands here and every operation
        on this pair is listed in `x-s3-operations` with its own tier. See `s3-model.json` for the authoritative
        form.'
      x-tier: core
      x-s3-operations:
      - operation: AbortMultipartUpload
        subresource: null
        tier: extended
        providers_declaring: 3
      - operation: DeleteObject
        subresource: null
        tier: core
        providers_declaring: 9
      - operation: DeleteObjectAnnotation
        subresource: annotation
        tier: vendor
        providers_declaring: 0
      - operation: DeleteObjectTagging
        subresource: tagging
        tier: vendor
        providers_declaring: 1
      parameters:
      - name: subresource
        in: query
        required: false
        description: The subresource selects the operation. Absent means the base operation on this method
          and path.
        schema:
          type: string
          enum:
          - annotation
          - tagging
      responses:
        '200':
          description: The operation's XML response. S3 is rest-xml, not JSON.
        '403':
          description: AccessDenied. Note that S3 validates the signature BEFORE routing the operation,
            so this answer does not distinguish an unsupported operation from an unauthorised one.
    get:
      operationId: GetObject
      summary: GET /{Bucket}/{Key+}
      description: '**10 S3 operations share this method and path.** They are distinguished by a query
        subresource, which an OpenAPI path cannot express, so `GetObject` stands here and every operation
        on this pair is listed in `x-s3-operations` with its own tier. See `s3-model.json` for the authoritative
        form.'
      x-tier: core
      x-s3-operations:
      - operation: GetObject
        subresource: null
        tier: core
        providers_declaring: 9
      - operation: GetObjectAcl
        subresource: acl
        tier: vendor
        providers_declaring: 0
      - operation: GetObjectAnnotation
        subresource: annotation
        tier: vendor
        providers_declaring: 0
      - operation: GetObjectAttributes
        subresource: attributes
        tier: vendor
        providers_declaring: 0
      - operation: GetObjectLegalHold
        subresource: legal-hold
        tier: vendor
        providers_declaring: 0
      - operation: GetObjectRetention
        subresource: retention
        tier: vendor
        providers_declaring: 0
      - operation: GetObjectTagging
        subresource: tagging
        tier: vendor
        providers_declaring: 1
      - operation: GetObjectTorrent
        subresource: torrent
        tier: vendor
        providers_declaring: 0
      - operation: ListObjectAnnotations
        subresource: annotation
        tier: vendor
        providers_declaring: 0
      - operation: ListParts
        subresource: null
        tier: vendor
        providers_declaring: 1
      parameters:
      - name: subresource
        in: query
        required: false
        description: The subresource selects the operation. Absent means the base operation on this method
          and path.
        schema:
          type: string
          enum:
          - acl
          - annotation
          - attributes
          - legal-hold
          - retention
          - tagging
          - torrent
      responses:
        '200':
          description: The operation's XML response. S3 is rest-xml, not JSON.
        '403':
          description: AccessDenied. Note that S3 validates the signature BEFORE routing the operation,
            so this answer does not distinguish an unsupported operation from an unauthorised one.
    head:
      operationId: HeadObject
      summary: HEAD /{Bucket}/{Key+}
      description: '**1 S3 operations share this method and path.** They are distinguished by a query
        subresource, which an OpenAPI path cannot express, so `HeadObject` stands here and every operation
        on this pair is listed in `x-s3-operations` with its own tier. See `s3-model.json` for the authoritative
        form.'
      x-tier: core
      x-s3-operations:
      - operation: HeadObject
        subresource: null
        tier: core
        providers_declaring: 7
      parameters: []
      responses:
        '200':
          description: The operation's XML response. S3 is rest-xml, not JSON.
        '403':
          description: AccessDenied. Note that S3 validates the signature BEFORE routing the operation,
            so this answer does not distinguish an unsupported operation from an unauthorised one.
    post:
      operationId: CreateMultipartUpload
      summary: POST /{Bucket}/{Key+}
      description: '**4 S3 operations share this method and path.** They are distinguished by a query
        subresource, which an OpenAPI path cannot express, so `CreateMultipartUpload` stands here and
        every operation on this pair is listed in `x-s3-operations` with its own tier. See `s3-model.json`
        for the authoritative form.'
      x-tier: extended
      x-s3-operations:
      - operation: CompleteMultipartUpload
        subresource: null
        tier: extended
        providers_declaring: 2
      - operation: CreateMultipartUpload
        subresource: uploads
        tier: extended
        providers_declaring: 5
      - operation: RestoreObject
        subresource: restore
        tier: vendor
        providers_declaring: 1
      - operation: SelectObjectContent
        subresource: select&select-type=2
        tier: vendor
        providers_declaring: 0
      parameters:
      - name: subresource
        in: query
        required: false
        description: The subresource selects the operation. Absent means the base operation on this method
          and path.
        schema:
          type: string
          enum:
          - restore
          - select&select-type
          - uploads
      responses:
        '200':
          description: The operation's XML response. S3 is rest-xml, not JSON.
        '403':
          description: AccessDenied. Note that S3 validates the signature BEFORE routing the operation,
            so this answer does not distinguish an unsupported operation from an unauthorised one.
    put:
      operationId: PutObject
      summary: PUT /{Bucket}/{Key+}
      description: '**11 S3 operations share this method and path.** They are distinguished by a query
        subresource, which an OpenAPI path cannot express, so `PutObject` stands here and every operation
        on this pair is listed in `x-s3-operations` with its own tier. See `s3-model.json` for the authoritative
        form.'
      x-tier: core
      x-s3-operations:
      - operation: CopyObject
        subresource: null
        tier: extended
        providers_declaring: 4
      - operation: PutObject
        subresource: null
        tier: core
        providers_declaring: 7
      - operation: PutObjectAcl
        subresource: acl
        tier: vendor
        providers_declaring: 0
      - operation: PutObjectAnnotation
        subresource: annotation
        tier: vendor
        providers_declaring: 0
      - operation: PutObjectLegalHold
        subresource: legal-hold
        tier: vendor
        providers_declaring: 0
      - operation: PutObjectRetention
        subresource: retention
        tier: vendor
        providers_declaring: 0
      - operation: PutObjectTagging
        subresource: tagging
        tier: vendor
        providers_declaring: 1
      - operation: RenameObject
        subresource: renameObject
        tier: vendor
        providers_declaring: 1
      - operation: UpdateObjectEncryption
        subresource: encryption
        tier: vendor
        providers_declaring: 0
      - operation: UploadPart
        subresource: null
        tier: extended
        providers_declaring: 3
      - operation: UploadPartCopy
        subresource: null
        tier: vendor
        providers_declaring: 0
      parameters:
      - name: subresource
        in: query
        required: false
        description: The subresource selects the operation. Absent means the base operation on this method
          and path.
        schema:
          type: string
          enum:
          - acl
          - annotation
          - encryption
          - legal-hold
          - renameObject
          - retention
          - tagging
      responses:
        '200':
          description: The operation's XML response. S3 is rest-xml, not JSON.
        '403':
          description: AccessDenied. Note that S3 validates the signature BEFORE routing the operation,
            so this answer does not distinguish an unsupported operation from an unauthorised one.
  /:
    get:
      operationId: ListBuckets
      summary: GET /
      description: '**2 S3 operations share this method and path.** They are distinguished by a query
        subresource, which an OpenAPI path cannot express, so `ListBuckets` stands here and every operation
        on this pair is listed in `x-s3-operations` with its own tier. See `s3-model.json` for the authoritative
        form.'
      x-tier: core
      x-s3-operations:
      - operation: ListBuckets
        subresource: null
        tier: core
        providers_declaring: 10
      - operation: ListDirectoryBuckets
        subresource: null
        tier: vendor
        providers_declaring: 0
      parameters: []
      responses:
        '200':
          description: The operation's XML response. S3 is rest-xml, not JSON.
        '403':
          description: AccessDenied. Note that S3 validates the signature BEFORE routing the operation,
            so this answer does not distinguish an unsupported operation from an unauthorised one.