Amazon SNS Subscriptions API

openapi: 3.1.0
info:
  title: Amazon SNS Amazon Simple Notification Service (SNS) ?Action=ListTagsForResource ?Action=ListTagsForResource Subscriptions API
  version: '2010-03-31'
  description: Amazon Simple Notification Service (SNS) is a fully managed pub/sub messaging service that enables application-to-application (A2A) and application-to-person (A2P) communication. SNS allows you to create topics, manage subscriptions, and publish messages to subscribers via multiple protocols including HTTP/S, email, SMS, SQS, Lambda, and mobile push. This specification models the SNS query API actions as RESTful paths for topic management, subscription lifecycle, and message publishing operations.
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/sns/
  termsOfService: https://aws.amazon.com/service-terms/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://sns.{region}.amazonaws.com
  description: Amazon SNS 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-southeast-1
      - ap-southeast-2
      - ap-northeast-1
      - ap-northeast-2
      - ap-south-1
      - sa-east-1
      - ca-central-1
security:
- AWS_IAM: []
tags:
- name: Subscriptions
  description: Operations for subscribing endpoints to topics, confirming subscriptions, listing subscriptions, and unsubscribing. Subscriptions define which endpoints receive messages published to a topic.
paths:
  /?Action=Subscribe:
    post:
      tags:
      - Subscriptions
      operationId: subscribe
      summary: Amazon Sns Subscribe an Endpoint to an Sns Topic
      description: Subscribes an endpoint to an Amazon SNS topic. If the endpoint type is HTTP/S or email, or if the endpoint and the topic are not in the same AWS account, the endpoint owner must run the ConfirmSubscription action to confirm the subscription. The subscription request is returned with a pending confirmation status.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - TopicArn
              - Protocol
              properties:
                TopicArn:
                  type: string
                  description: The ARN of the topic to subscribe to
                Protocol:
                  type: string
                  description: The protocol to use for delivery
                  enum:
                  - http
                  - https
                  - email
                  - email-json
                  - sms
                  - sqs
                  - application
                  - lambda
                  - firehose
                Endpoint:
                  type: string
                  description: 'The endpoint that you want to receive notifications. Endpoints vary by protocol: an email address for email, a URL for HTTP/S, an ARN for SQS/Lambda/Firehose, a phone number for SMS, or a device token ARN for application.'
                Attributes:
                  type: object
                  description: Subscription attributes
                  properties:
                    FilterPolicy:
                      type: string
                      description: A JSON string defining the filter policy that determines which messages the subscriber receives
                    FilterPolicyScope:
                      type: string
                      description: Specifies whether the filter policy applies to message attributes or the message body
                      enum:
                      - MessageAttributes
                      - MessageBody
                    DeliveryPolicy:
                      type: string
                      description: The delivery retry policy (JSON) for HTTP/S endpoints
                    RawMessageDelivery:
                      type: string
                      description: When set to true, the message is delivered as a raw message without SNS metadata wrapping
                      enum:
                      - 'true'
                      - 'false'
                    RedrivePolicy:
                      type: string
                      description: A JSON string specifying the dead-letter queue ARN for failed message delivery
                    SubscriptionRoleArn:
                      type: string
                      description: The ARN of the IAM role that has permission to write to the Amazon Kinesis Data Firehose stream
                ReturnSubscriptionArn:
                  type: boolean
                  description: When set to true, the response includes the subscription ARN even if the subscription is not yet confirmed
      responses:
        '200':
          description: Subscription created or pending confirmation
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/SubscribeResponse'
        '400':
          $ref: '#/components/responses/InvalidParameter'
        '403':
          $ref: '#/components/responses/AuthorizationError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /?Action=ConfirmSubscription:
    post:
      tags:
      - Subscriptions
      operationId: confirmSubscription
      summary: Amazon Sns Confirm a Pending Subscription
      description: Verifies an endpoint owner's intent to receive messages by validating the token sent to the endpoint by an earlier Subscribe action. If the token is valid, the action creates a new subscription and returns its Amazon Resource Name (ARN).
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - TopicArn
              - Token
              properties:
                TopicArn:
                  type: string
                  description: The ARN of the topic for which you wish to confirm a subscription
                Token:
                  type: string
                  description: Short-lived token sent to an endpoint during the Subscribe action
                AuthenticateOnUnsubscribe:
                  type: string
                  description: If set to true, disallows unauthenticated unsubscribes. Only the topic owner and subscription owner can unsubscribe.
                  enum:
                  - 'true'
                  - 'false'
      responses:
        '200':
          description: Subscription confirmed
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ConfirmSubscriptionResponse'
        '400':
          $ref: '#/components/responses/InvalidParameter'
        '403':
          $ref: '#/components/responses/AuthorizationError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /?Action=Unsubscribe:
    post:
      tags:
      - Subscriptions
      operationId: unsubscribe
      summary: Amazon Sns Unsubscribe From an Sns Topic
      description: Deletes a subscription. If the subscription requires authentication for deletion, only the owner of the subscription or the topic's owner can unsubscribe, and an AWS signature is required. If the Unsubscribe call does not require authentication and the requester is not the subscription owner, a final cancellation message is delivered to the endpoint.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - SubscriptionArn
              properties:
                SubscriptionArn:
                  type: string
                  description: The ARN of the subscription to be deleted
      responses:
        '200':
          description: Unsubscribed successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/UnsubscribeResponse'
        '403':
          $ref: '#/components/responses/AuthorizationError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /?Action=ListSubscriptions:
    get:
      tags:
      - Subscriptions
      operationId: listSubscriptions
      summary: Amazon Sns List All Subscriptions
      description: Returns a list of the requester's subscriptions. Each call returns a limited list of subscriptions, up to 100. If there are more subscriptions, a NextToken is also returned. Use the NextToken parameter in a new ListSubscriptions call to get further results.
      parameters:
      - name: NextToken
        in: query
        description: Token returned by the previous request for pagination
        schema:
          type: string
      responses:
        '200':
          description: List of subscriptions
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ListSubscriptionsResponse'
        '403':
          $ref: '#/components/responses/AuthorizationError'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /?Action=ListSubscriptionsByTopic:
    get:
      tags:
      - Subscriptions
      operationId: listSubscriptionsByTopic
      summary: Amazon Sns List Subscriptions for a Specific Topic
      description: Returns a list of the subscriptions to a specific topic. Each call returns a limited list of subscriptions, up to 100. If there are more subscriptions, a NextToken is also returned.
      parameters:
      - name: TopicArn
        in: query
        required: true
        description: The ARN of the topic for which you wish to list subscriptions
        schema:
          type: string
      - name: NextToken
        in: query
        description: Token returned by the previous request for pagination
        schema:
          type: string
      responses:
        '200':
          description: List of subscriptions for the topic
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ListSubscriptionsByTopicResponse'
        '403':
          $ref: '#/components/responses/AuthorizationError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /?Action=GetSubscriptionAttributes:
    get:
      tags:
      - Subscriptions
      operationId: getSubscriptionAttributes
      summary: Amazon Sns Get Attributes of a Subscription
      description: Returns all of the properties of a subscription.
      parameters:
      - name: SubscriptionArn
        in: query
        required: true
        description: The ARN of the subscription whose properties you want to get
        schema:
          type: string
      responses:
        '200':
          description: Subscription attributes retrieved
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/GetSubscriptionAttributesResponse'
        '403':
          $ref: '#/components/responses/AuthorizationError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /?Action=SetSubscriptionAttributes:
    post:
      tags:
      - Subscriptions
      operationId: setSubscriptionAttributes
      summary: Amazon Sns Set Attributes on a Subscription
      description: Allows a subscription owner to set an attribute of the subscription to a new value.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - SubscriptionArn
              - AttributeName
              properties:
                SubscriptionArn:
                  type: string
                  description: The ARN of the subscription to modify
                AttributeName:
                  type: string
                  description: The attribute name. Valid values include DeliveryPolicy, FilterPolicy, FilterPolicyScope, RawMessageDelivery, and RedrivePolicy.
                AttributeValue:
                  type: string
                  description: The new value for the attribute
      responses:
        '200':
          description: Attribute set successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/SetSubscriptionAttributesResponse'
        '400':
          $ref: '#/components/responses/InvalidParameter'
        '403':
          $ref: '#/components/responses/AuthorizationError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    ListSubscriptionsByTopicResponse:
      type: object
      properties:
        ListSubscriptionsByTopicResult:
          type: object
          properties:
            Subscriptions:
              type: array
              items:
                $ref: '#/components/schemas/SubscriptionMember'
            NextToken:
              type: string
              description: Token for paginating results
          example: example_value
        ResponseMetadata:
          $ref: '#/components/schemas/ResponseMetadata'
    SetSubscriptionAttributesResponse:
      type: object
      properties:
        ResponseMetadata:
          $ref: '#/components/schemas/ResponseMetadata'
    SubscriptionMember:
      type: object
      properties:
        SubscriptionArn:
          type: string
          description: The subscription ARN
          example: example_value
        Owner:
          type: string
          description: The subscription owner's AWS account ID
          example: example_value
        Protocol:
          type: string
          description: The subscription protocol
          example: example_value
        Endpoint:
          type: string
          description: The subscription endpoint
          example: example_value
        TopicArn:
          type: string
          description: The topic ARN that this subscription is associated with
          example: example_value
    ConfirmSubscriptionResponse:
      type: object
      properties:
        ConfirmSubscriptionResult:
          type: object
          properties:
            SubscriptionArn:
              type: string
              description: The ARN of the created subscription
          example: example_value
        ResponseMetadata:
          $ref: '#/components/schemas/ResponseMetadata'
    SubscribeResponse:
      type: object
      properties:
        SubscribeResult:
          type: object
          properties:
            SubscriptionArn:
              type: string
              description: The ARN of the subscription. For pending subscriptions, this value is 'pending confirmation'.
          example: example_value
        ResponseMetadata:
          $ref: '#/components/schemas/ResponseMetadata'
    UnsubscribeResponse:
      type: object
      properties:
        ResponseMetadata:
          $ref: '#/components/schemas/ResponseMetadata'
    ErrorResponse:
      type: object
      properties:
        Error:
          type: object
          properties:
            Type:
              type: string
              description: The error type (Sender or Receiver)
            Code:
              type: string
              description: The specific error code
            Message:
              type: string
              description: A human-readable description of the error
          example: example_value
        RequestId:
          type: string
          description: The unique request identifier
          example: '500123'
    GetSubscriptionAttributesResponse:
      type: object
      properties:
        GetSubscriptionAttributesResult:
          type: object
          properties:
            Attributes:
              type: object
              description: A map of the subscription attributes
              additionalProperties:
                type: string
          example: example_value
        ResponseMetadata:
          $ref: '#/components/schemas/ResponseMetadata'
    ListSubscriptionsResponse:
      type: object
      properties:
        ListSubscriptionsResult:
          type: object
          properties:
            Subscriptions:
              type: array
              items:
                $ref: '#/components/schemas/SubscriptionMember'
            NextToken:
              type: string
              description: Token for paginating results
          example: example_value
        ResponseMetadata:
          $ref: '#/components/schemas/ResponseMetadata'
    ResponseMetadata:
      type: object
      properties:
        RequestId:
          type: string
          description: The unique request identifier
          example: '500123'
  responses:
    InternalError:
      description: Internal service error
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    AuthorizationError:
      description: Authorization error - insufficient permissions
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The requested resource does not exist
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InvalidParameter:
      description: Invalid parameter in the request
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    AWS_IAM:
      type: http
      scheme: bearer
      description: AWS Signature Version 4 authentication. Requests must be signed using IAM credentials with appropriate SNS permissions. See https://docs.aws.amazon.com/general/latest/gr/signing_aws_api_requests.html
externalDocs:
  description: Amazon SNS API Reference
  url: https://docs.aws.amazon.com/sns/latest/api/welcome.html