Amazon S3 Annotation API

The annotation API from Amazon S3 — 1 operation(s) for annotation.

GitHub OpenAPI

Operations 4

DELETE /{Bucket}/{Key+}?annotation Delete Object Annotation #
PUT /{Bucket}/{Key+}?annotation Put Object Annotation #
GET /{Bucket}/{Key+}?annotation&x-id=GetObjectAnnotation Get Object Annotation #
GET /{Bucket}/{Key+}?annotation&x-id=ListObjectAnnotations List Object Annotations #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/amazon-s3:amazon-s3-annotation-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

amazon-s3-annotation-api-openapi.yml Raw ↑
openapi: 3.1.0
info:
  title: Amazon Simple Storage Service Annotation API
  version: '2006-03-01'
  description: Generated from AWS's published Smithy model for Amazon Simple Storage Service. 4 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://s3.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
paths:
  /{Bucket}/{Key+}?annotation:
    delete:
      operationId: DeleteObjectAnnotation
      summary: Delete Object Annotation
      description: 'Deletes a specific annotation from an Amazon S3 object. Use the x-amz-object-if-match header to perform
        a conditional delete that only succeeds if the object''s ETag matches the provided value, preventing race conditions
        during concurrent updates. Deleting an annotation is permanent. Annotations are not independently versioned, so there
        is no delete marker or way to recover a deleted annotation. To use this operation, you must have the s3:DeleteObjectAnnotation
        permission. If the object is protected by Object Lock in governance mode, you must also include the x-amz-bypass-governance-retention
        header. Annotations are not supported by the following features: S3 Inventory Reports, API Gateway, S3 Storage Lens,
        Amazon S3 File Gateway, Amazon FSx, S3 on Outposts, and S3 Express One Zone (directory buckets). The following operations
        are related to DeleteObjectAnnotation: PutObjectAnnotation GetObjectAnnotation ListObjectAnnotations'
      responses:
        '200':
          description: Success
          content:
            text/xml:
              schema:
                $ref: '#/components/schemas/DeleteObjectAnnotationOutput'
        '404':
          description: NoSuchBucket; NoSuchKey
          content:
            text/xml:
              schema:
                $ref: '#/components/schemas/NoSuchBucket'
      parameters:
      - name: Bucket
        in: path
        required: true
        schema:
          type: string
        description: The name of the bucket that contains the object.
      - name: Key
        in: path
        required: true
        schema:
          type: string
        description: The object key.
      - name: annotationName
        in: query
        required: true
        schema:
          type: string
        description: 'The name of the annotation to delete. Annotation names are UTF-8 encoded and cannot start with aws or
          s3 (case-insensitive). Length Constraints: Minimum length of 1. Maximum length of 512 bytes.'
      - name: versionId
        in: query
        schema:
          type: string
        description: The version ID of the object.
      - name: x-amz-request-payer
        in: header
        schema:
          type: string
          enum:
          - requester
      - name: x-amz-expected-bucket-owner
        in: header
        schema:
          type: string
        description: The account ID of the expected bucket owner.
      - name: x-amz-object-if-match
        in: header
        schema:
          type: string
        description: If specified, the operation only succeeds if the object's ETag matches the provided value.
      tags:
      - Annotation
    put:
      operationId: PutObjectAnnotation
      summary: Put Object Annotation
      description: 'Attaches an annotation to an Amazon S3 object. An annotation is a named payload of 1 byte to 1 MiB that
        you can associate with a specific object or object version. Each object can have up to 1,000 annotations. For annotation
        naming rules and restrictions, see Annotation naming guidelines in the Amazon S3 User Guide. Annotations inherit the
        encryption of their parent object. For objects without server-side encryption, annotations are encrypted with SSE-S3
        (the default for new objects). Objects encrypted with SSE-C cannot have annotations. To use this operation, you must
        have the s3:PutObjectAnnotation permission. If the bucket has Requester Pays enabled, you must include the x-amz-request-payer
        header. Annotations are not supported by the following features: S3 Inventory Reports, API Gateway, S3 Storage Lens,
        Amazon S3 File Gateway, Amazon FSx, S3 on Outposts, and S3 Express One Zone (directory buckets). The following operations
        are related to PutObjectAnnotation: GetObjectAnnotation ListObjectAnnotations DeleteObjectAnnotation'
      responses:
        '200':
          description: Success
          content:
            text/xml:
              schema:
                $ref: '#/components/schemas/PutObjectAnnotationOutput'
        '400':
          description: AnnotationLimitExceeded; AnnotationNameTooLong; InvalidAnnotationName; InvalidRequest
          content:
            text/xml:
              schema:
                $ref: '#/components/schemas/AnnotationLimitExceeded'
        '404':
          description: NoSuchBucket; NoSuchKey
          content:
            text/xml:
              schema:
                $ref: '#/components/schemas/NoSuchBucket'
        '415':
          description: UnsupportedMediaType
          content:
            text/xml:
              schema:
                $ref: '#/components/schemas/UnsupportedMediaType'
      parameters:
      - name: Bucket
        in: path
        required: true
        schema:
          type: string
        description: The name of the bucket that contains the object.
      - name: Key
        in: path
        required: true
        schema:
          type: string
        description: The object key.
      - name: versionId
        in: query
        schema:
          type: string
        description: The version ID of the object to attach the annotation to.
      - name: annotationName
        in: query
        required: true
        schema:
          type: string
        description: 'The name of the annotation. Length Constraints: Minimum length of 1. Maximum length of 512 bytes.'
      - name: x-amz-object-if-match
        in: header
        schema:
          type: string
        description: If specified, the operation only succeeds if the object's ETag matches the provided value.
      - name: x-amz-sdk-checksum-algorithm
        in: header
        schema:
          type: string
          enum:
          - CRC32
          - CRC32C
          - SHA1
          - SHA256
          - CRC64NVME
          - SHA512
          - MD5
          - XXHASH64
          - XXHASH3
          - XXHASH128
        description: 'The checksum algorithm to use. Supported values: CRC32, CRC32C, CRC64NVME, SHA1, SHA256, SHA512, MD5,
          XXHASH64, XXHASH3, XXHASH128.'
      - name: x-amz-checksum-crc32
        in: header
        schema:
          type: string
        description: Base64-encoded CRC32 checksum of the annotation payload.
      - name: x-amz-checksum-crc32c
        in: header
        schema:
          type: string
        description: Base64-encoded CRC32C checksum of the annotation payload.
      - name: x-amz-checksum-crc64nvme
        in: header
        schema:
          type: string
        description: Base64-encoded CRC64NVME checksum of the annotation payload.
      - name: x-amz-checksum-sha1
        in: header
        schema:
          type: string
        description: Base64-encoded SHA1 checksum of the annotation payload.
      - name: x-amz-checksum-sha256
        in: header
        schema:
          type: string
        description: Base64-encoded SHA256 checksum of the annotation payload.
      - name: x-amz-checksum-sha512
        in: header
        schema:
          type: string
        description: Base64-encoded SHA512 checksum of the annotation payload.
      - name: x-amz-checksum-md5
        in: header
        schema:
          type: string
        description: Base64-encoded MD5 checksum of the annotation payload.
      - name: x-amz-checksum-xxhash64
        in: header
        schema:
          type: string
        description: Base64-encoded XXHASH64 checksum of the annotation payload.
      - name: x-amz-checksum-xxhash3
        in: header
        schema:
          type: string
        description: Base64-encoded XXHASH3 checksum of the annotation payload.
      - name: x-amz-checksum-xxhash128
        in: header
        schema:
          type: string
        description: Base64-encoded XXHASH128 checksum of the annotation payload.
      - name: Content-MD5
        in: header
        schema:
          type: string
        description: Base64-encoded MD5 digest of the message.
      - name: x-amz-request-payer
        in: header
        schema:
          type: string
          enum:
          - requester
      - name: x-amz-expected-bucket-owner
        in: header
        schema:
          type: string
        description: The account ID of the expected bucket owner. If the bucket is owned by a different account, the request
          fails with an HTTP 403 (Access Denied) error.
      requestBody:
        content:
          application/xml:
            schema:
              type: string
              format: byte
      tags:
      - Annotation
  /{Bucket}/{Key+}?annotation&x-id=GetObjectAnnotation:
    get:
      operationId: GetObjectAnnotation
      summary: Get Object Annotation
      description: 'Retrieves an annotation from an Amazon S3 object. To use this operation, you must have the s3:GetObjectAnnotation
        permission. If checksum mode is enabled via the x-amz-checksum-mode header, Amazon S3 returns the stored checksum
        in the response headers for client-side validation. Annotations are not supported by the following features: S3 Inventory
        Reports, API Gateway, S3 Storage Lens, Amazon S3 File Gateway, Amazon FSx, S3 on Outposts, and S3 Express One Zone
        (directory buckets). The following operations are related to GetObjectAnnotation: PutObjectAnnotation ListObjectAnnotations
        DeleteObjectAnnotation'
      responses:
        '200':
          description: Success
          content:
            text/xml:
              schema:
                $ref: '#/components/schemas/GetObjectAnnotationOutput'
        '404':
          description: NoSuchAnnotation; NoSuchBucket; NoSuchKey
          content:
            text/xml:
              schema:
                $ref: '#/components/schemas/NoSuchAnnotation'
      parameters:
      - name: Bucket
        in: path
        required: true
        schema:
          type: string
        description: The name of the bucket that contains the object.
      - name: Key
        in: path
        required: true
        schema:
          type: string
        description: The object key.
      - name: annotationName
        in: query
        required: true
        schema:
          type: string
        description: 'The name of the annotation to retrieve. Length Constraints: Minimum length of 1. Maximum length of 512
          bytes.'
      - name: versionId
        in: query
        schema:
          type: string
        description: The version ID of the object.
      - name: x-amz-request-payer
        in: header
        schema:
          type: string
          enum:
          - requester
      - name: x-amz-expected-bucket-owner
        in: header
        schema:
          type: string
        description: The account ID of the expected bucket owner. If the bucket is owned by a different account, the request
          fails with an HTTP 403 (Access Denied) error.
      - name: x-amz-checksum-mode
        in: header
        schema:
          type: string
          enum:
          - ENABLED
        description: Set to ENABLED to validate the checksum of the annotation payload on retrieval.
      tags:
      - Annotation
  /{Bucket}/{Key+}?annotation&x-id=ListObjectAnnotations:
    get:
      operationId: ListObjectAnnotations
      summary: List Object Annotations
      description: 'Lists the annotations attached to an Amazon S3 object. Results are paginated, with a maximum of 1,000
        annotations per object. Use the AnnotationPrefix parameter to filter the results by name prefix. To use this operation,
        you must have the s3:ListObjectAnnotations permission. Annotations are not supported by the following features: S3
        Inventory Reports, API Gateway, S3 Storage Lens, Amazon S3 File Gateway, Amazon FSx, S3 on Outposts, and S3 Express
        One Zone (directory buckets). The following operations are related to ListObjectAnnotations: PutObjectAnnotation GetObjectAnnotation
        DeleteObjectAnnotation'
      responses:
        '200':
          description: Success
          content:
            text/xml:
              schema:
                $ref: '#/components/schemas/ListObjectAnnotationsOutput'
        '400':
          description: InvalidPrefix
          content:
            text/xml:
              schema:
                $ref: '#/components/schemas/InvalidPrefix'
        '404':
          description: NoSuchBucket; NoSuchKey
          content:
            text/xml:
              schema:
                $ref: '#/components/schemas/NoSuchBucket'
      parameters:
      - name: Bucket
        in: path
        required: true
        schema:
          type: string
        description: The name of the bucket that contains the object.
      - name: Key
        in: path
        required: true
        schema:
          type: string
        description: The object key.
      - name: versionId
        in: query
        schema:
          type: string
        description: The version ID of the object.
      - name: max-annotation-results
        in: query
        schema:
          type: integer
        description: The maximum number of annotations to return in the response. Maximum is 1,000.
      - name: annotation-prefix
        in: query
        schema:
          type: string
        description: Filter results to annotations whose name begins with the specified prefix.
      - name: continuation-token
        in: query
        schema:
          type: string
        description: Continuation token returned by a previous request to retrieve the next page.
      - name: x-amz-request-payer
        in: header
        schema:
          type: string
          enum:
          - requester
      - name: x-amz-expected-bucket-owner
        in: header
        schema:
          type: string
        description: The account ID of the expected bucket owner.
      tags:
      - Annotation
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: s3
  schemas:
    AnnotationEntry:
      type: object
      properties:
        AnnotationName:
          type: string
          description: The name of the annotation.
        LastModified:
          type: string
          format: date-time
          description: The date and time the annotation was last modified.
        ETag:
          type: string
          description: The entity tag of the annotation.
        ChecksumAlgorithm:
          type: array
          items:
            type: string
            enum:
            - CRC32
            - CRC32C
            - SHA1
            - SHA256
            - CRC64NVME
            - SHA512
            - MD5
            - XXHASH64
            - XXHASH3
            - XXHASH128
          description: The checksum algorithm used for the annotation.
        Size:
          type: integer
          description: The size of the annotation payload, in bytes.
        ReplicationStatus:
          type: string
          enum:
          - COMPLETE
          - PENDING
          - FAILED
          - REPLICA
          - COMPLETED
          description: The replication status of the annotation.
      required:
      - AnnotationName
      - LastModified
      - Size
    AnnotationLimitExceeded:
      type: object
      properties: {}
    DeleteObjectAnnotationOutput:
      type: object
      properties:
        ObjectVersionId:
          type: string
          description: The version ID of the object that the annotation was deleted from.
        RequestCharged:
          type: string
          enum:
          - requester
    GetObjectAnnotationOutput:
      type: object
      properties:
        AnnotationPayload:
          type: string
          format: byte
          description: The annotation payload.
        ObjectVersionId:
          type: string
          description: The version ID of the object that the annotation is attached to.
        LastModified:
          type: string
          format: date-time
          description: The date and time the annotation was last modified.
        ContentLength:
          type: integer
          description: The size of the annotation payload, in bytes.
        ETag:
          type: string
          description: The entity tag of the annotation.
        ChecksumCRC32:
          type: string
          description: The CRC32 checksum of the annotation payload.
        ChecksumCRC32C:
          type: string
          description: The CRC32C checksum of the annotation payload.
        ChecksumCRC64NVME:
          type: string
          description: The CRC64NVME checksum of the annotation payload.
        ChecksumSHA1:
          type: string
          description: The SHA1 checksum of the annotation payload.
        ChecksumSHA256:
          type: string
          description: The SHA256 checksum of the annotation payload.
        ChecksumSHA512:
          type: string
          description: The SHA512 checksum of the annotation payload.
        ChecksumMD5:
          type: string
          description: The MD5 checksum of the annotation payload.
        ChecksumXXHASH64:
          type: string
          description: The XXHASH64 checksum of the annotation payload.
        ChecksumXXHASH3:
          type: string
          description: The XXHASH3 checksum of the annotation payload.
        ChecksumXXHASH128:
          type: string
          description: The XXHASH128 checksum of the annotation payload.
        ChecksumType:
          type: string
          enum:
          - COMPOSITE
          - FULL_OBJECT
          description: The type of checksum used.
        ServerSideEncryption:
          type: string
          enum:
          - AES256
          - aws:fsx
          - aws:backup
          - aws:kms
          - aws:kms:dsse
          description: The server-side encryption algorithm used.
        RequestCharged:
          type: string
          enum:
          - requester
        ReplicationStatus:
          type: string
          enum:
          - COMPLETE
          - PENDING
          - FAILED
          - REPLICA
          - COMPLETED
          description: The replication status of the annotation. Possible values include PENDING, COMPLETED, FAILED, and REPLICA.
    InvalidPrefix:
      type: object
      properties: {}
    ListObjectAnnotationsOutput:
      type: object
      properties:
        Annotations:
          type: array
          items:
            $ref: '#/components/schemas/AnnotationEntry'
          description: The list of annotations attached to the object.
        Bucket:
          type: string
          description: The bucket name.
        Key:
          type: string
          description: The object key.
        ObjectVersionId:
          type: string
          description: The version ID of the object.
        AnnotationPrefix:
          type: string
          description: The prefix used to filter the response.
        MaxAnnotationResults:
          type: integer
          description: The maximum number of annotations returned in the response.
        AnnotationCount:
          type: integer
          description: The number of annotations returned.
        ContinuationToken:
          type: string
          description: The continuation token used in this request.
        NextContinuationToken:
          type: string
          description: The continuation token to use to retrieve the next page of results.
        RequestCharged:
          type: string
          enum:
          - requester
    NoSuchAnnotation:
      type: object
      properties: {}
    NoSuchBucket:
      type: object
      properties: {}
    PutObjectAnnotationOutput:
      type: object
      properties:
        Key:
          type: string
          description: The object key.
        AnnotationName:
          type: string
          description: The name of the annotation.
        ObjectVersionId:
          type: string
          description: The version ID of the object that the annotation was attached to.
        ETag:
          type: string
          description: The entity tag of the annotation.
        ChecksumCRC32:
          type: string
          description: The CRC32 checksum of the stored annotation.
        ChecksumCRC32C:
          type: string
          description: The CRC32C checksum of the stored annotation.
        ChecksumCRC64NVME:
          type: string
          description: The CRC64NVME checksum of the stored annotation.
        ChecksumSHA1:
          type: string
          description: The SHA1 checksum of the stored annotation.
        ChecksumSHA256:
          type: string
          description: The SHA256 checksum of the stored annotation.
        ChecksumSHA512:
          type: string
          description: The SHA512 checksum of the stored annotation.
        ChecksumMD5:
          type: string
          description: The MD5 checksum of the stored annotation.
        ChecksumXXHASH64:
          type: string
          description: The XXHASH64 checksum of the stored annotation.
        ChecksumXXHASH3:
          type: string
          description: The XXHASH3 checksum of the stored annotation.
        ChecksumXXHASH128:
          type: string
          description: The XXHASH128 checksum of the stored annotation.
        ChecksumType:
          type: string
          enum:
          - COMPOSITE
          - FULL_OBJECT
          description: The type of checksum used.
        ServerSideEncryption:
          type: string
          enum:
          - AES256
          - aws:fsx
          - aws:backup
          - aws:kms
          - aws:kms:dsse
          description: The server-side encryption algorithm used to encrypt the annotation.
        RequestCharged:
          type: string
          enum:
          - requester
    UnsupportedMediaType:
      type: object
      properties: {}
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/3cd98287b471c106254abd89279cc87308d38bfd/models/s3/service/2006-03-01/s3-2006-03-01.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)