openapi: 3.0.3
info:
  title: Semrush Hermes Partner API API
  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
tags:
- name: Hermes Partner API
paths:
  /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:
  schemas:
    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'
    errorMessage:
      type: string
      maxLength: 256
      description: A text message describing an error
    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'
    responseMeta:
      type: object
      description: Response metadata
      properties:
        success:
          type: boolean
        status_code:
          type: integer
          example: 200
        request_id:
          type: string
    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

        '
    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'
    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
    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
    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
  responses:
    '401':
      description: Unauthorized. Incorrect JWT fields or signature
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorMessage'
    '400':
      description: Bad request. Something wrong with the request or JWT
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorMessage'
  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)

        '