Amazon SNS Topics API

openapi: 3.1.0
info:
  title: Amazon SNS Amazon Simple Notification Service (SNS) ?Action=ListTagsForResource ?Action=ListTagsForResource Topics 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: Topics
  description: Operations for creating, listing, configuring, and deleting SNS topics. Topics are communication channels to which messages are published and from which notifications are delivered to subscribers.
paths:
  /?Action=CreateTopic:
    post:
      tags:
      - Topics
      operationId: createTopic
      summary: Amazon Sns Create a New Sns Topic
      description: Creates a new SNS topic to which notifications can be published. Topics can be standard or FIFO. Returns the TopicArn of the newly created topic. If a topic with the same name already exists, this action returns the TopicArn of the existing topic.
      parameters:
      - $ref: '#/components/parameters/ContentType'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - Name
              properties:
                Name:
                  type: string
                  description: The name of the topic to create. Topic names must be unique within an AWS account. For FIFO topics, the name must end with the .fifo suffix.
                  maxLength: 256
                  pattern: ^[a-zA-Z0-9_-]+(\\.fifo)?$
                Attributes:
                  type: object
                  description: A map of topic attributes to set on creation.
                  properties:
                    DisplayName:
                      type: string
                      description: The display name for the topic used in email subject lines
                    Policy:
                      type: string
                      description: The access policy (JSON) for the topic
                    DeliveryPolicy:
                      type: string
                      description: The delivery retry policy (JSON) for HTTP/S subscriptions
                    KmsMasterKeyId:
                      type: string
                      description: The ID of an AWS KMS key for server-side encryption of messages published to this topic
                    FifoTopic:
                      type: string
                      description: Set to true to create a FIFO topic
                      enum:
                      - 'true'
                      - 'false'
                    ContentBasedDeduplication:
                      type: string
                      description: Enables content-based deduplication for FIFO topics. Messages with identical content are treated as duplicates within the deduplication interval.
                      enum:
                      - 'true'
                      - 'false'
                    SignatureVersion:
                      type: string
                      description: The signature version for SNS message signing. Version 1 uses SHA1, version 2 uses SHA256.
                      enum:
                      - '1'
                      - '2'
                    TracingConfig:
                      type: string
                      description: Tracing mode for the topic
                      enum:
                      - Active
                      - PassThrough
                Tags:
                  type: array
                  description: Tags to add to the new topic
                  items:
                    $ref: '#/components/schemas/Tag'
                DataProtectionPolicy:
                  type: string
                  description: The data protection policy (JSON) that defines sensitive data auditing, de-identification, and masking operations
      responses:
        '200':
          description: Topic created successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/CreateTopicResponse'
        '400':
          $ref: '#/components/responses/InvalidParameter'
        '403':
          $ref: '#/components/responses/AuthorizationError'
        '429':
          $ref: '#/components/responses/Throttled'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /?Action=DeleteTopic:
    post:
      tags:
      - Topics
      operationId: deleteTopic
      summary: Amazon Sns Delete an Sns Topic
      description: Deletes a topic and all its subscriptions. Deleting a topic might prevent some messages previously sent to the topic from being delivered to subscribers. This action is idempotent, so deleting a topic that does not exist does not result in an error.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - TopicArn
              properties:
                TopicArn:
                  type: string
                  description: The ARN of the topic to delete
      responses:
        '200':
          description: Topic deleted successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/DeleteTopicResponse'
        '403':
          $ref: '#/components/responses/AuthorizationError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /?Action=ListTopics:
    get:
      tags:
      - Topics
      operationId: listTopics
      summary: Amazon Sns List All Sns Topics
      description: Returns a list of the requester's topics. Each call returns a limited list of topics, up to 100. If there are more topics, a NextToken is also returned. Use the NextToken parameter in a new ListTopics call to get further results.
      parameters:
      - name: NextToken
        in: query
        description: Token returned by the previous ListTopics request for pagination
        schema:
          type: string
      responses:
        '200':
          description: List of topics
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ListTopicsResponse'
        '403':
          $ref: '#/components/responses/AuthorizationError'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /?Action=GetTopicAttributes:
    get:
      tags:
      - Topics
      operationId: getTopicAttributes
      summary: Amazon Sns Get Attributes of an Sns Topic
      description: Returns all of the properties of a topic. Topic properties returned might differ based on the authorization of the user.
      parameters:
      - name: TopicArn
        in: query
        required: true
        description: The ARN of the topic whose properties you want to get
        schema:
          type: string
      responses:
        '200':
          description: Topic attributes retrieved
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/GetTopicAttributesResponse'
        '403':
          $ref: '#/components/responses/AuthorizationError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /?Action=SetTopicAttributes:
    post:
      tags:
      - Topics
      operationId: setTopicAttributes
      summary: Amazon Sns Set Attributes on an Sns Topic
      description: Allows a topic owner to set an attribute of the topic to a new value. Only one attribute can be changed per call.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - TopicArn
              - AttributeName
              properties:
                TopicArn:
                  type: string
                  description: The ARN of the topic to modify
                AttributeName:
                  type: string
                  description: The name of the attribute to set. Valid values include Policy, DisplayName, DeliveryPolicy, KmsMasterKeyId, SignatureVersion, TracingConfig, and others.
                AttributeValue:
                  type: string
                  description: The new value for the attribute
      responses:
        '200':
          description: Attribute set successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/SetTopicAttributesResponse'
        '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:
  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'
    Throttled:
      description: Request rate exceeded - throttled
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ResponseMetadata:
      type: object
      properties:
        RequestId:
          type: string
          description: The unique request identifier
          example: '500123'
    TopicMember:
      type: object
      properties:
        TopicArn:
          type: string
          description: The ARN of the topic
          example: example_value
    ListTopicsResponse:
      type: object
      properties:
        ListTopicsResult:
          type: object
          properties:
            Topics:
              type: array
              items:
                $ref: '#/components/schemas/TopicMember'
            NextToken:
              type: string
              description: Token for paginating results
          example: example_value
        ResponseMetadata:
          $ref: '#/components/schemas/ResponseMetadata'
    SetTopicAttributesResponse:
      type: object
      properties:
        ResponseMetadata:
          $ref: '#/components/schemas/ResponseMetadata'
    CreateTopicResponse:
      type: object
      properties:
        CreateTopicResult:
          type: object
          properties:
            TopicArn:
              type: string
              description: The Amazon Resource Name assigned to the created topic
          example: example_value
        ResponseMetadata:
          $ref: '#/components/schemas/ResponseMetadata'
    DeleteTopicResponse:
      type: object
      properties:
        ResponseMetadata:
          $ref: '#/components/schemas/ResponseMetadata'
    Tag:
      type: object
      required:
      - Key
      - Value
      properties:
        Key:
          type: string
          description: The tag key
          minLength: 1
          maxLength: 128
          example: example_value
        Value:
          type: string
          description: The tag value
          maxLength: 256
          example: example_value
    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'
    GetTopicAttributesResponse:
      type: object
      properties:
        GetTopicAttributesResult:
          type: object
          properties:
            Attributes:
              type: object
              description: A map of the topic attributes
              additionalProperties:
                type: string
          example: example_value
        ResponseMetadata:
          $ref: '#/components/schemas/ResponseMetadata'
  parameters:
    ContentType:
      name: Content-Type
      in: header
      description: Content type for form-encoded requests
      schema:
        type: string
        default: application/x-www-form-urlencoded
  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