Amazon S3 REST API

openapi: 3.1.0
info:
  title: Amazon S3 REST API
  description: >-
    Amazon Simple Storage Service (Amazon S3) is an object storage service that
    offers industry-leading scalability, data availability, security, and
    performance. The Amazon S3 REST API uses standard HTTP requests to create,
    fetch, and delete buckets and objects. All S3 REST API operations are
    authenticated using AWS Signature Version 4.
  version: '2006-03-01'
  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
externalDocs:
  description: Amazon S3 API Reference
  url: https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html
servers:
- url: https://s3.{region}.amazonaws.com
  description: Amazon S3 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-northeast-3
      - ap-southeast-1
      - ap-southeast-2
      - ap-south-1
      - sa-east-1
      - ca-central-1
      - af-south-1
      - me-south-1
- url: https://{bucket}.s3.{region}.amazonaws.com
  description: Amazon S3 virtual-hosted-style endpoint
  variables:
    bucket:
      default: my-bucket
      description: The name of the S3 bucket
    region:
      default: us-east-1
      description: AWS region
security:
- sigv4: []
tags:
- name: Access Control
  description: Operations for managing bucket and object access control lists (ACLs)
- name: Bucket Configuration
  description: Operations for managing bucket-level configuration such as versioning, lifecycle, CORS, and encryption
- name: Buckets
  description: Operations for creating, listing, and managing S3 buckets
- name: Multipart Upload
  description: Operations for multipart upload of large objects
- name: Objects
  description: Operations for uploading, downloading, copying, and deleting objects
- name: Tagging
  description: Operations for managing bucket and object tags
paths:
  /:
    get:
      operationId: ListBuckets
      summary: Amazon S3 List Buckets
      description: >-
        Returns a list of all buckets owned by the authenticated sender of the
        request. To use this operation, you must have the s3:ListAllMyBuckets
        permission. This operation uses the GET method on the service endpoint.
      tags:
      - Buckets
      parameters:
      - name: x-amz-expected-bucket-owner
        in: header
        description: The account ID of the expected bucket owner.
        schema:
          type: string
        example: example_value
      responses:
        '200':
          description: Successfully returned list of buckets.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ListAllMyBucketsResult'
              examples:
                Listbuckets200Example:
                  summary: Default ListBuckets 200 response
                  x-microcks-default: true
                  value:
                    Owner:
                      DisplayName: example_value
                      ID: abc123
                    Buckets:
                      Bucket:
                      - {}
          headers:
            x-amz-request-id:
              description: Unique identifier for the request.
              schema:
                type: string
        '403':
          description: Access denied. The requester does not have permission.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Listbuckets403Example:
                  summary: Default ListBuckets 403 response
                  x-microcks-default: true
                  value:
                    Code: example_value
                    Message: example_value
                    Resource: example_value
                    RequestId: '500123'
                    HostId: '500123'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{Bucket}:
    put:
      operationId: CreateBucket
      summary: Amazon S3 Create Bucket
      description: >-
        Creates a new S3 bucket. To create a bucket, you must register with
        Amazon S3 and have a valid AWS Access Key ID. By default, buckets are
        created in the us-east-1 region. Use the LocationConstraint request
        element to specify a different region.
      tags:
      - Buckets
      parameters:
      - $ref: '#/components/parameters/BucketName'
      - name: x-amz-acl
        in: header
        description: The canned ACL to apply to the bucket.
        schema:
          type: string
          enum:
          - private
          - public-read
          - public-read-write
          - authenticated-read
        example: private
      - name: x-amz-bucket-object-lock-enabled
        in: header
        description: >-
          Specifies whether you want S3 Object Lock to be enabled for the new
          bucket.
        schema:
          type: boolean
        example: true
      - name: x-amz-object-ownership
        in: header
        description: The container element for object ownership.
        schema:
          type: string
          enum:
          - BucketOwnerPreferred
          - ObjectWriter
          - BucketOwnerEnforced
        example: BucketOwnerPreferred
      requestBody:
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/CreateBucketConfiguration'
            examples:
              CreatebucketRequestExample:
                summary: Default CreateBucket request
                x-microcks-default: true
                value:
                  LocationConstraint: af-south-1
                  Location:
                    Name: Example Title
                    Type: AvailabilityZone
                  Bucket:
                    DataRedundancy: SingleAvailabilityZone
                    Type: Directory
      responses:
        '200':
          description: Bucket created successfully.
          headers:
            Location:
              description: >-
                The URI of the newly created bucket, including the path-style
                endpoint.
              schema:
                type: string
        '409':
          description: >-
            BucketAlreadyExists or BucketAlreadyOwnedByYou. The requested bucket
            name is not available.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Createbucket409Example:
                  summary: Default CreateBucket 409 response
                  x-microcks-default: true
                  value:
                    Code: example_value
                    Message: example_value
                    Resource: example_value
                    RequestId: '500123'
                    HostId: '500123'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: DeleteBucket
      summary: Amazon S3 Delete Bucket
      description: >-
        Deletes the S3 bucket. All objects in the bucket must be deleted before
        the bucket itself can be deleted. The bucket owner can always delete a
        bucket, regardless of bucket policies.
      tags:
      - Buckets
      parameters:
      - $ref: '#/components/parameters/BucketName'
      - name: x-amz-expected-bucket-owner
        in: header
        description: The account ID of the expected bucket owner.
        schema:
          type: string
        example: example_value
      responses:
        '204':
          description: Bucket deleted successfully.
        '404':
          description: The specified bucket does not exist.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Deletebucket404Example:
                  summary: Default DeleteBucket 404 response
                  x-microcks-default: true
                  value:
                    Code: example_value
                    Message: example_value
                    Resource: example_value
                    RequestId: '500123'
                    HostId: '500123'
        '409':
          description: The bucket you tried to delete is not empty.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Deletebucket409Example:
                  summary: Default DeleteBucket 409 response
                  x-microcks-default: true
                  value:
                    Code: example_value
                    Message: example_value
                    Resource: example_value
                    RequestId: '500123'
                    HostId: '500123'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    head:
      operationId: HeadBucket
      summary: Amazon S3 Head Bucket
      description: >-
        Determines if a bucket exists and you have permission to access it. A
        HEAD request returns 200 OK if the bucket exists and you have permission
        to access it. Returns 404 Not Found if the bucket does not exist or 403
        Forbidden if you do not have permission.
      tags:
      - Buckets
      parameters:
      - $ref: '#/components/parameters/BucketName'
      - name: x-amz-expected-bucket-owner
        in: header
        description: The account ID of the expected bucket owner.
        schema:
          type: string
      responses:
        '200':
          description: The bucket exists and you have access.
          headers:
            x-amz-bucket-region:
              description: The region where the bucket is located.
              schema:
                type: string
            x-amz-access-point-alias:
              description: Indicates whether the bucket name is an access point alias.
              schema:
                type: boolean
        '301':
          description: The bucket exists in a different region.
        '403':
          description: Forbidden. You do not have permission to access this bucket.
        '404':
          description: The specified bucket does not exist.
  /{Bucket}?list-type=2:
    get:
      operationId: ListObjectsV2
      summary: Amazon S3 List Objects V2
      description: >-
        Returns some or all (up to 1,000) of the objects in a bucket with each
        request. You can use the request parameters as selection criteria to
        return a subset of the objects in a bucket. This is the recommended
        approach for listing objects. ListObjectsV2 supersedes the older
        ListObjects API.
      tags:
      - Objects
      parameters:
      - $ref: '#/components/parameters/BucketName'
      - name: list-type
        in: query
        required: true
        description: Set to 2 to use the ListObjectsV2 API.
        schema:
          type: integer
          enum:
          - 2
        example: 2
      - name: continuation-token
        in: query
        description: >-
          ContinuationToken indicates to S3 that the list is being continued
          on this bucket with a token returned in a previous response.
        schema:
          type: string
        example: example_value
      - name: delimiter
        in: query
        description: >-
          A delimiter is a character that you use to group keys. All keys that
          contain the same string between the prefix and the first occurrence
          of the delimiter are grouped under a single CommonPrefixes element.
        schema:
          type: string
        example: example_value
      - name: encoding-type
        in: query
        description: Encoding type used by Amazon S3 to encode object keys in the response.
        schema:
          type: string
          enum:
          - url
        example: url
      - name: fetch-owner
        in: query
        description: Set to true to include the owner field in the response.
        schema:
          type: boolean
        example: true
      - name: max-keys
        in: query
        description: >-
          Sets the maximum number of keys returned in the response. By default,
          the action returns up to 1,000 key names.
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 1000
        example: 10
      - name: prefix
        in: query
        description: Limits the response to keys that begin with the specified prefix.
        schema:
          type: string
        example: example_value
      - name: start-after
        in: query
        description: >-
          StartAfter is where you want Amazon S3 to start listing from. S3
          starts listing after this specified key.
        schema:
          type: string
        example: example_value
      - name: x-amz-expected-bucket-owner
        in: header
        description: The account ID of the expected bucket owner.
        schema:
          type: string
        example: example_value
      - name: x-amz-request-payer
        in: header
        description: Confirms that the requester knows they will be charged for the request.
        schema:
          type: string
          enum:
          - requester
        example: requester
      - name: x-amz-optional-object-attributes
        in: header
        description: Specifies the optional metadata attributes to include in the response.
        schema:
          type: string
        example: example_value
      responses:
        '200':
          description: Successfully returned list of objects.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ListBucketResult'
              examples:
                Listobjectsv2200Example:
                  summary: Default ListObjectsV2 200 response
                  x-microcks-default: true
                  value:
                    IsTruncated: true
                    Contents:
                    - Key: example_value
                      LastModified: '2026-01-15T10:30:00Z'
                      ETag: example_value
                      Size: 10
                      StorageClass: STANDARD
                      ChecksumAlgorithm: {}
                      RestoreStatus: {}
                    Name: Example Title
                    Prefix: example_value
                    Delimiter: example_value
                    MaxKeys: 10
                    CommonPrefixes:
                    - Prefix: example_value
                    EncodingType: example_value
                    KeyCount: 10
                    ContinuationToken: example_value
                    NextContinuationToken: example_value
                    StartAfter: example_value
        '403':
          description: Access denied.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Listobjectsv2403Example:
                  summary: Default ListObjectsV2 403 response
                  x-microcks-default: true
                  value:
                    Code: example_value
                    Message: example_value
                    Resource: example_value
                    RequestId: '500123'
                    HostId: '500123'
        '404':
          description: The specified bucket does not exist.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Listobjectsv2404Example:
                  summary: Default ListObjectsV2 404 response
                  x-microcks-default: true
                  value:
                    Code: example_value
                    Message: example_value
                    Resource: example_value
                    RequestId: '500123'
                    HostId: '500123'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{Bucket}/{Key+}:
    get:
      operationId: GetObject
      summary: Amazon S3 Get Object
      description: >-
        Retrieves objects from Amazon S3. To use GET, you must have READ access
        to the object. You can grant READ access using a bucket policy or an
        object ACL. Supports conditional retrieval using If-Match,
        If-None-Match, If-Modified-Since, and If-Unmodified-Since headers.
        Supports range reads with the Range header.
      tags:
      - Objects
      parameters:
      - $ref: '#/components/parameters/BucketName'
      - $ref: '#/components/parameters/ObjectKey'
      - name: response-cache-control
        in: query
        description: Sets the Cache-Control header of the response.
        schema:
          type: string
        example: example_value
      - name: response-content-disposition
        in: query
        description: Sets the Content-Disposition header of the response.
        schema:
          type: string
        example: example_value
      - name: response-content-encoding
        in: query
        description: Sets the Content-Encoding header of the response.
        schema:
          type: string
        example: example_value
      - name: response-content-language
        in: query
        description: Sets the Content-Language header of the response.
        schema:
          type: string
        example: example_value
      - name: response-content-type
        in: query
        description: Sets the Content-Type header of the response.
        schema:
          type: string
        example: example_value
      - name: response-expires
        in: query
        description: Sets the Expires header of the response.
        schema:
          type: string
        example: example_value
      - name: versionId
        in: query
        description: VersionId used to reference a specific version of the object.
        schema:
          type: string
        example: '500123'
      - name: partNumber
        in: query
        description: Part number of the object being read for a multipart object.
        schema:
          type: integer
        example: 10
      - name: Range
        in: header
        description: >-
          Downloads the specified range bytes of an object. For more
          information, see RFC 9110 Section 14.2.
        schema:
          type: string
        example: example_value
      - name: If-Match
        in: header
        description: >-
          Return the object only if its entity tag (ETag) matches the
          specified tag.
        schema:
          type: string
        example: example_value
      - name: If-None-Match
        in: header
        description: >-
          Return the object only if its entity tag (ETag) differs from the
          specified tag.
        schema:
          type: string
        example: example_value
      - name: If-Modified-Since
        in: header
        description: Return the object only if it has been modified since the specified time.
        schema:
          type: string
          format: date-time
        example: '2026-01-15T10:30:00Z'
      - name: If-Unmodified-Since
        in: header
        description: >-
          Return the object only if it has not been modified since the
          specified time.
        schema:
          type: string
          format: date-time
        example: '2026-01-15T10:30:00Z'
      - name: x-amz-server-side-encryption-customer-algorithm
        in: header
        description: >-
          Specifies the algorithm to use to when decrypting the object
          (AES256).
        schema:
          type: string
        example: example_value
      - name: x-amz-server-side-encryption-customer-key
        in: header
        description: >-
          Specifies the customer-provided encryption key for Amazon S3 used to
          encrypt the data.
        schema:
          type: string
        example: example_value
      - name: x-amz-server-side-encryption-customer-key-MD5
        in: header
        description: >-
          Specifies the 128-bit MD5 digest of the encryption key according to
          RFC 1321.
        schema:
          type: string
        example: example_value
      - name: x-amz-request-payer
        in: header
        description: >-
          Confirms that the requester knows that they will be charged for the
          request.
        schema:
          type: string
          enum:
          - requester
        example: requester
      - name: x-amz-expected-bucket-owner
        in: header
        description: The account ID of the expected bucket owner.
        schema:
          type: string
        example: example_value
      - name: x-amz-checksum-mode
        in: header
        description: >-
          To retrieve the checksum, this mode must be enabled. Set to ENABLED.
        schema:
          type: string
          enum:
          - ENABLED
        example: ENABLED
      responses:
        '200':
          description: Successfully retrieved the object.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
              examples:
                Getobject200Example:
                  summary: Default GetObject 200 response
                  x-microcks-default: true
                  value: example_value
          headers:
            Content-Length:
              description: Size of the body in bytes.
              schema:
                type: integer
            Content-Type:
              description: A standard MIME type describing the format of the object data.
              schema:
                type: string
            ETag:
              description: An opaque identifier assigned to the object.
              schema:
                type: string
            Last-Modified:
              description: Date and time the object was last modified.
              schema:
                type: string
                format: date-time
            x-amz-version-id:
              description: Version of the object.
              schema:
                type: string
            x-amz-delete-marker:
              description: Specifies whether the object retrieved was a delete marker.
              schema:
                type: boolean
            x-amz-storage-class:
              description: Amazon S3 storage class of the object.
              schema:
                type: string
            x-amz-server-side-encryption:
              description: >-
                The server-side encryption algorithm used when storing this
                object.
              schema:
                type: string
            Cache-Control:
              description: Specifies caching behavior along the request/reply chain.
              schema:
                type: string
            Content-Disposition:
              description: Specifies presentational information for the object.
              schema:
                type: string
            Content-Encoding:
              description: >-
                Specifies what content encodings have been applied to the object.
              schema:
                type: string
            Content-Language:
              description: The language the content is in.
              schema:
                type: string
            x-amz-expiration:
              description: >-
                If the object expiration is configured, the response includes
                this header.
              schema:
                type: string
            x-amz-restore:
              description: >-
                Provides information about object restoration action and
                expiration time of the restored copy.
              schema:
                type: string
            x-amz-object-lock-mode:
              description: The Object Lock mode applied to the object.
              schema:
                type: string
            x-amz-object-lock-retain-until-date:
              description: The date and time when the Object Lock retention period expires.
              schema:
                type: string
                format: date-time
            x-amz-object-lock-legal-hold:
              description: Specifies whether a legal hold is in effect for the object.
              schema:
                type: string
            x-amz-replication-status:
              description: Replication status of the object.
              schema:
                type: string
        '206':
          description: Partial content returned for range request.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
              examples:
                Getobject206Example:
                  summary: Default GetObject 206 response
                  x-microcks-default: true
                  value: example_value
        '304':
          description: Not modified.
        '403':
          description: Access denied.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Getobject403Example:
                  summary: Default GetObject 403 response
                  x-microcks-default: true
                  value:
                    Code: example_value
                    Message: example_value
                    Resource: example_value
                    RequestId: '500123'
                    HostId: '500123'
        '404':
          description: The specified key does not exist.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Getobject404Example:
                  summary: Default GetObject 404 response
                  x-microcks-default: true
                  value:
                    Code: example_value
                    Message: example_value
                    Resource: example_value
                    RequestId: '500123'
                    HostId: '500123'
        '412':
          description: Precondition failed.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Getobject412Example:
                  summary: Default GetObject 412 response
                  x-microcks-default: true
                  value:
                    Code: example_value
                    Message: example_value
                    Resource: example_value
                    RequestId: '500123'
                    HostId: '500123'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: PutObject
      summary: Amazon S3 Put Object
      description: >-
        Adds an object to a bucket. You must have WRITE permissions on a bucket
        to add an object to it. Amazon S3 never adds partial objects; if you
        receive a success response, Amazon S3 added the entire object to the
        bucket. Objects can be up to 5 GiB in size when uploaded in a single PUT
        operation. For larger objects, use multipart upload.
      tags:
      - Objects
      parameters:
      - $ref: '#/components/parameters/BucketName'
      - $ref: '#/components/parameters/ObjectKey'
      - name: Cache-Control
        in: header
        description: >-
          Can be used to specify caching behavior along the request/reply
          chain.
        schema:
          type: string
        example: example_value
      - name: Content-Disposition
        in: header
        description: Specifies presentational information for the object.
        schema:
          type: string
        example: example_value
      - name: Content-Encoding
        in: header
        description: >-
          Specifies what content encodings have been applied to the object.
        schema:
          type: string
        example: example_value
      - name: Content-Language
        in: header
        description: The language the content is in.
        schema:
          type: string
        example: example_value
      - name: Content-Length
        in: header
        description: >-
          Size of the body in bytes. This parameter is useful when the size of
          the body cannot be determined automatically.
        schema:
          type: integer
        example: 10
      - name: Content-MD5
        in: header
        description: The base64-encoded 128-bit MD5 digest of the message.
        schema:
          type: string
        example: example_value
      - name: Content-Type
        in: header
        description: A standard MIME type describing the format of the contents.
        schema:
          type: string
        example: example_value
      - name: Expires
        in: header
        description: The date and time at which the object is no longer cacheable.
        schema:
          type: string
          format: date-time
        example: '2026-01-15T10:30:00Z'
      - name: x-amz-acl
        in: header
        description: The canned ACL to apply to the object.
        schema:
          type: string
          enum:
          - private
          - public-read
          - public-read-write
          - authenticated-read
          - aws-exec-read
          - bucket-owner-read
          - bucket-owner-full-control
        example: private
      - name: x-amz-storage-class
        in: header
        description: Amazon S3 storage class to use for storing the object.
        schema:
          type: string
          enum:
          - STANDARD
          - REDUCED_REDUNDANCY
          - STANDARD_IA
          - ONEZONE_IA
          - INTELLIGENT_TIERING
          - GLACIER
          - DEEP_ARCHIVE
          - OUTPOSTS
          - GLACIER_IR
          - SNOW
          - EXPRESS_ONEZONE
        example: STANDARD
      - name: x-amz-server-side-encryption
        in: header
        description: >-
          The server-side encryption algorithm used when storing this object in
          Amazon S3.
        schema:
          type: string
          enum:
          - AES256
          - aws:kms
          - aws:kms:dsse
        example: AES256
      - name: x-amz-server-side-encryption-aws-kms-key-id
        in: header
        description: >-
          If x-amz-server-side-encryption is aws:kms or aws:kms:dsse,
          specifies the ID of the KMS key.
        schema:
          type: string
        example: '500123'
      - name: x-amz-server-side-encryption-context
        in: header
        description: >-
          Specifies the AWS KMS Encryption Context to use for object
          encryption.
        schema:
          type: string
        example: example_value
      - name: x-amz-server-side-encryption-bucket-key-enabled
        in: header
        description: >-
          Specifies whether S3 should use an S3 Bucket Key for object
          encryption with server-side encryption using AWS KMS.
        schema:
          type: boolean
        example: true
      - name: x-amz-server-side-encryption-customer-algorithm
        in: header
        description: >-
          Specifies the algorithm to use to encrypt the object (AES256).
        schema:
          type: string
        example: example_value
      - name: x-amz-server-side-encryption-customer-key
        in: header
        description: >-
          Specifies the customer-provided encryption key.
        schema:
          type: string
        example: example_value
      - name: x-amz-server-side-encryption-customer-key-MD5
        in: header
        description: >-
          Specifies the 128-bit MD5 digest of the encryption key.
        schema:
          type: string
        example: example_value
      - name: x-amz-tagging
        in: header
        description: The tag-set for the object. Must be encoded as URL query parameters.
        schema:
          type: string
        example: example_value
      - name: x-amz-object-lock-mode
        in: header
        description: The Object Lock mode that you want to apply to the uploaded object.
        schema:
 

# --- truncated at 32 KB (125 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/amazon-s3/refs/heads/main/openapi/amazon-s3-rest-api-openapi.yml