openapi: 3.0.3
info:
  title: Semrush
  version: 0.0.1
  description: >-
    SEMrush is an all-in-one digital marketing tool that helps businesses
    improve their online visibility and attract more customers. This powerful
    software provides a range of tools and features for keyword research,
    website analysis, competitive analysis, and more. With SEMrush, businesses
    can track their online rankings, discover new keywords to target, analyze
    their competitors' strategies, and optimize their website for better search
    engine performance. Overall, SEMrush is a essential tool for any business
    looking to succeed in the competitive world of online marketing.
servers:
  - url: https://api.semrush.com
paths:
  /app-center-api/v2/jwt-token/:
    post:
      tags:
        - JWT Issuer
      summary: Semrush Request API access token
      description: >
        Retrieves JWT for accessing Semrush API.

        [Documentation](https://www.semrush.com/apps/docs/server-to-server-api/bearer-token)
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/issuerJwtRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/issuerJwtResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          description: Access denied
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/errorMessage'
  /apis/v4/app-center/v2/partner/viewer-status:
    post:
      tags:
        - Partner Service
      summary: Semrush User status
      description: >
        Retrieves user status, related to the app (purchases, subscriptions)

        [Documentation](https://www.semrush.com/apps/docs/server-to-server-api/viewer-status)
      security:
        - jwtIssuerToken: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/viewerStatusRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/viewerStatusResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
  /apis/v4/hermes/v0/subscriptions:
    get:
      tags:
        - Hermes Partner API
      summary: Semrush Get available subscriptions
      description: >
        List all application's registered subscriptions

        [Documentation](https://www.semrush.com/apps/docs/server-to-server-api/notifications#available-subscriptions)
      security:
        - jwtIssuerToken: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/appSubscriptionsResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
  /apis/v4/hermes/v0/user/{user_id}/subscription/{id}:
    get:
      tags:
        - Hermes Partner API
      summary: Semrush Get user's subscription status
      description: >
        [Documentation](https://www.semrush.com/apps/docs/server-to-server-api/notifications#subscription-status)
      security:
        - jwtIssuerToken: []
      parameters:
        - in: path
          name: user_id
          schema:
            type: integer
          required: true
          description: User id
        - in: path
          name: id
          schema:
            type: integer
          required: true
          description: Subscription id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/appUserSubscriptionStatusResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
  /apis/v4/hermes/v0/event:
    post:
      tags:
        - Hermes Partner API
      summary: Semrush Send notification
      description: >
        [Documentation](https://www.semrush.com/apps/docs/server-to-server-api/notifications#sending-notification)
      security:
        - jwtIssuerToken: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createEventRequest'
      responses:
        '201':
          description: Created
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
  /apis/v4/hermes/v0/event/{id}:
    get:
      tags:
        - Hermes Partner API
      summary: Semrush Get event status
      description: >
        [Documentation](https://www.semrush.com/apps/docs/server-to-server-api/notifications#event-status)
      security:
        - jwtIssuerToken: []
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
            description: Global event identifier
          required: true
          description: Subscription id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/eventResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
components:
  responses:
    '400':
      description: Bad request. Something wrong with the request or JWT
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorMessage'
    '401':
      description: Unauthorized. Incorrect JWT fields or signature
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorMessage'
  schemas:
    actionNotification:
      type: object
      description: Action notification details
      properties:
        channel:
          type: string
          description: Sending channel
        subscription_id:
          type: integer
          description: ID of subscription
        recipient_id:
          type: integer
          description: ID of subscriber
    eventAction:
      type: object
      description: Action that can be taken on event
      properties:
        id:
          type: string
          format: uuid
          description: Global action identifier
        ts:
          type: string
          format: date-time
          description: Action create time in ISO format
        type:
          type: string
          example: notification
          description: Action type
        finished:
          type: boolean
          description: Did action accomplished
        notification:
          $ref: '#/components/schemas/actionNotification'
    eventState:
      type: integer
      enum:
        - 1
        - 2
        - 3
        - 4
        - 5
      description: |
        State of event processing.
        * 1 - Event has been registered and awaiting processing
        * 2 - Event processing was delayed
        * 3 - Event was processed
        * 4 - Event has nothing to do with
        * 5 - Event processing was blocked by internal rules
    eventResponse:
      type: object
      description: Create event response object
      properties:
        meta:
          $ref: '#/components/schemas/responseMeta'
        data:
          type: object
          description: Event status response
          properties:
            id:
              type: string
              format: uuid
              description: Global event identifier
            ts:
              type: string
              format: date-time
              description: Event registration time in ISO format
            state:
              $ref: '#/components/schemas/eventState'
            state_on:
              type: string
              format: date-time
              description: Time when event get in current state in ISO format
            decision:
              type: string
              description: Processing decision
            actions:
              type: array
              description: Actions taken on event
              items:
                $ref: '#/components/schemas/eventAction'
    eventAttachment:
      type: object
      description: Event additional files
      properties:
        name:
          type: string
          description: File name
        mime:
          type: string
          example: application/pdf
          description: File content mime type
        content:
          type: string
          format: byte
          example: eyJkYXRhX2tleSI6ImRhdGFfdmFsdWUxIn0=
          description: File content in Base64
    createEventRequest:
      type: object
      properties:
        type:
          type: string
          description: type of event
        id:
          type: string
          format: uuid
          description: >-
            UUID, global event identifier, idempotency key; we suggest using V4
            UUIDs
        user_id:
          type: integer
          description: Semrush's user ID
        data:
          type: string
          format: byte
          example: eyJkYXRhX2tleSI6ImRhdGFfdmFsdWUxIn0=
        attachments:
          type: array
          description: Additional files
          items:
            $ref: '#/components/schemas/eventAttachment'
    appUserSubscriptionStatusResponse:
      type: object
      description: User subscription status response object
      properties:
        meta:
          $ref: '#/components/schemas/responseMeta'
        data:
          type: object
          description: An object describes subscription status related to user
          properties:
            active:
              type: boolean
              description: Does user subscribed on requested subscription
    appSubscriptionsResponse:
      type: object
      description: Available subscriptions response object
      properties:
        meta:
          $ref: '#/components/schemas/responseMeta'
        data:
          type: object
          description: An object describes all app subscriptions
          properties:
            subscriptions:
              type: array
              description: app subscriptions
              items:
                type: object
                description: available subscription
                properties:
                  id:
                    type: integer
                    description: Subscription ID
                  name:
                    type: string
                    description: Subscription name
                  description:
                    type: string
                    description: Subscription description
    viewerActiveProduct:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: UUID of product
        value:
          type: integer
          description: >-
            Amount of bought product (1 for one-time products, >1 in other
            cases)
          minimum: 0
    viewerStatusResponse:
      type: object
      description: Viewer Status response object
      properties:
        meta:
          $ref: '#/components/schemas/responseMeta'
        data:
          type: object
          description: An object describes user status, related to the app
          properties:
            is_main_product_active:
              type: boolean
              description: Shows if the app's main product is active
            is_app_taken_for_free:
              type: boolean
              description: Shows if the app is taken for free
            is_main_product_trial_available:
              type: boolean
              description: true if a user can activate trial for app's main product
            product_trials_available:
              type: array
              description: All app's products ids, for which user can activate trial
              items:
                type: string
                format: uuid
                description: product id
            active_products:
              type: array
              description: List of user's in-app purchases (bought products)
              minItems: 0
              items:
                $ref: '#/components/schemas/viewerActiveProduct'
            extra_user_data:
              type: object
              nullable: true
              description: Reserved for future use
    responseMeta:
      type: object
      description: Response metadata
      properties:
        success:
          type: boolean
        status_code:
          type: integer
          example: 200
        request_id:
          type: string
    viewerStatusRequest:
      type: object
      properties:
        user_id:
          type: integer
          description: Semrush user ID
    errorMessage:
      type: string
      maxLength: 256
      description: A text message describing an error
    issuerErrorMessage:
      type: object
      description: An object describing an error
      properties:
        message:
          type: string
        message_code:
          type: string
        code:
          type: integer
    issuerJwtRequest:
      type: object
      properties:
        jwt:
          type: string
          description: >
            JWT by
            [specification](https://www.semrush.com/apps/docs/server-to-server-api/bearer-token#generate-a-jwt), 

            signed by your secret key
          example: >-
            eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...0NiL86tQkUG25G3Y1QC2ma94sfe4cXcs8_bYcpw2OzY
    issuerJwtResponse:
      type: object
      description: An object describing a JWT
      properties:
        jwt:
          type: string
          example: >-
            eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...0NiL86tQkUG25G3Y1QC2ma94sfe4cXcs8_bYcpw2OzY
  securitySchemes:
    jwtIssuerToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        Use token retrieved from Jwt Issuer

        [Documentation](https://www.semrush.com/apps/docs/server-to-server-api/bearer-token)
tags:
  - name: Hermes Partner API
  - name: JWT Issuer
  - name: Partner Service