Matomo Custom Alerts API

openapi: 3.2.0
info:
  title: Matomo Reporting API for plugin Custom Alerts API
  version: 1.0.0
  description: Exposes Custom Alerts API endpoints for managing alert definitions and reading triggered alert data. These methods let callers create, update, fetch, delete, and evaluate alerts for one or more sites.
servers:
- url: https://demo-proxy.innocraft.cloud/
  description: Current Matomo instance
security:
- MatomoToken: []
tags:
- name: CustomAlerts
  description: Exposes Custom Alerts API endpoints for managing alert definitions and reading triggered alert data. These methods let callers create, update, fetch, delete, and evaluate alerts for one or more sites.
paths:
  /index.php?module=API&method=CustomAlerts.getValuesForAlertInPast:
    get:
      tags:
      - CustomAlerts
      description: Returns the computed alert value for each site linked to an alert for a past or current period.
      operationId: CustomAlerts.getValuesForAlertInPast
      parameters:
      - $ref: '#/components/parameters/formatOptional'
      - name: idAlert
        in: query
        description: Alert ID to evaluate.
        required: true
        schema:
          type: integer
          example: 1
      - name: subPeriodN
        in: query
        description: Number of periods in the past to evaluate. Use 0 for the current day, week, or month.
        required: true
        schema:
          oneOf:
          - type: integer
            example: 1
          - type: string
            example: '1'
      responses:
        '200':
          description: 'Alert values grouped by site.


            Example responses require Super User access. Use Try it out to see a live response.'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/DefaultError'
  /index.php?module=API&method=CustomAlerts.getAlert:
    get:
      tags:
      - CustomAlerts
      description: Returns a single custom alert definition.
      operationId: CustomAlerts.getAlert
      parameters:
      - $ref: '#/components/parameters/formatOptional'
      - name: idAlert
        in: query
        description: Alert ID to fetch.
        required: true
        schema:
          type: integer
          example: 1
      responses:
        '200':
          description: 'Alert definition including the configured site IDs.


            Example responses require Super User access. Use Try it out to see a live response.'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/DefaultError'
  /index.php?module=API&method=CustomAlerts.getAlerts:
    get:
      tags:
      - CustomAlerts
      description: Returns the custom alerts configured for the requested sites.
      operationId: CustomAlerts.getAlerts
      parameters:
      - $ref: '#/components/parameters/formatOptional'
      - name: idSites
        in: query
        description: Website ID(s) to query. Accepts comma-separated IDs, "all", numeric IDs as strings, or ["all"].
        required: true
        schema:
          oneOf:
          - type: string
          - type: array
            items: []
        example: '[1,2]'
      - name: ifSuperUserReturnAllAlerts
        in: query
        description: Whether a super user should receive alerts created by all users.
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: 'Alert definitions accessible to the current user for the requested sites.


            Example responses require Super User access. Use Try it out to see a live response.'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/DefaultError'
  /index.php?module=API&method=CustomAlerts.addAlert:
    get:
      tags:
      - CustomAlerts
      description: Creates a custom alert for one or more sites.
      operationId: CustomAlerts.addAlert
      parameters:
      - $ref: '#/components/parameters/formatOptional'
      - name: name
        in: query
        description: Alert name.
        required: true
        schema:
          type: string
          example: Pricing
      - name: idSites
        in: query
        description: Website ID(s) to query. Accepts comma-separated IDs, "all", numeric IDs as strings, or ["all"].
        required: true
        schema:
          oneOf:
          - type: string
          - type: array
            items: []
        example: '[1,2]'
      - name: period
        in: query
        description: 'Alert period. Allowed values: day, week, month.'
        required: true
        schema:
          type: string
          enum:
          - day
          - week
          - month
          example: day
      - name: emailMe
        in: query
        description: Whether to notify the current user by email when the alert triggers.
        required: true
        schema:
          type: boolean
          example: true
      - name: additionalEmails
        in: query
        description: Additional email recipients for email notifications.
        required: true
        schema:
          type: array
          items:
            type: string
          example:
          - alice@example.org
      - name: phoneNumbers
        in: query
        description: Mobile Messaging recipients when the mobile channel is enabled.
        required: true
        schema:
          type: array
          items:
            type: string
          example:
          - '+64211234567'
      - name: metric
        in: query
        description: Metric unique ID to evaluate, for example nb_uniq_visits or sum_visit_length.
        required: true
        schema:
          type: string
          example: nb_visits
      - name: metricCondition
        in: query
        description: 'Comparison rule to apply to the metric. Allowed values: less_than, greater_than, decrease_more_than, increase_more_than, percentage_decrease_more_than, percentage_increase_more_than.'
        required: true
        schema:
          type: string
          example: nb_conversions
      - name: metricValue
        in: query
        description: Threshold value to compare the selected metric against.
        required: true
        schema:
          oneOf:
          - type: number
            example: 10
          - type: integer
            example: 10
          - type: string
            example: '10'
      - name: comparedTo
        in: query
        description: 'Number of prior periods to compare against. Allowed values by period: day => 1, 7, 365; week => 1; month => 1, 12.'
        required: true
        schema:
          type: integer
          example: 1
      - name: reportUniqueId
        in: query
        description: Report unique ID in module_action format.
        required: true
        schema:
          type: string
          example: VisitsSummary_get
      - name: reportCondition
        in: query
        description: 'Optional dimension filter condition for report rows. Allowed values: matches_any, matches_exactly, does_not_match_exactly, matches_regex, does_not_match_regex, contains, does_not_contain, starts_with, does_not_start_with, ends_with, does_not_end_with.'
        required: false
        schema:
          type: string
      - name: reportValue
        in: query
        description: Value to match when $reportCondition is provided.
        required: false
        schema:
          type: string
      - name: reportMediums
        in: query
        description: 'Delivery channels to use for notifications. Allowed values: email, mobile, slack, teams.'
        required: false
        schema:
          type: array
          items: []
          default: []
      - name: slackChannelID
        in: query
        description: Slack channel ID when the slack channel is enabled.
        required: false
        schema:
          type: string
          default: ''
      - name: msTeamsWebhookUrl
        in: query
        description: Microsoft Teams webhook URL when the teams channel is enabled.
        required: false
        schema:
          type: string
          default: ''
      - name: description
        in: query
        description: Optional alert description (max 255 characters).
        required: false
        schema:
          type: string
          default: ''
      responses:
        '200':
          description: 'ID of the newly created alert.


            Example responses require Super User access. Use Try it out to see a live response.'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/DefaultError'
  /index.php?module=API&method=CustomAlerts.editAlert:
    get:
      tags:
      - CustomAlerts
      description: Updates an existing custom alert.
      operationId: CustomAlerts.editAlert
      parameters:
      - $ref: '#/components/parameters/formatOptional'
      - name: idAlert
        in: query
        description: Alert ID to update.
        required: true
        schema:
          type: integer
          example: 1
      - name: name
        in: query
        description: Alert name.
        required: true
        schema:
          type: string
          example: Pricing
      - name: idSites
        in: query
        description: Website ID(s) to query. Accepts comma-separated IDs, "all", numeric IDs as strings, or ["all"].
        required: true
        schema:
          oneOf:
          - type: string
          - type: array
            items: []
        example: '[1,2]'
      - name: period
        in: query
        description: 'Alert period. Allowed values: day, week, month.'
        required: true
        schema:
          type: string
          enum:
          - day
          - week
          - month
          example: day
      - name: emailMe
        in: query
        description: Whether to notify the current user by email when the alert triggers.
        required: true
        schema:
          type: boolean
          example: true
      - name: additionalEmails
        in: query
        description: Additional email recipients for email notifications.
        required: true
        schema:
          type: array
          items:
            type: string
          example:
          - alice@example.org
      - name: phoneNumbers
        in: query
        description: Mobile Messaging recipients when the mobile channel is enabled.
        required: true
        schema:
          type: array
          items:
            type: string
          example:
          - '+64211234567'
      - name: metric
        in: query
        description: Metric unique ID to evaluate, for example nb_uniq_visits or sum_visit_length.
        required: true
        schema:
          type: string
          example: nb_visits
      - name: metricCondition
        in: query
        description: 'Comparison rule to apply to the metric. Allowed values: less_than, greater_than, decrease_more_than, increase_more_than, percentage_decrease_more_than, percentage_increase_more_than.'
        required: true
        schema:
          type: string
          example: nb_conversions
      - name: metricValue
        in: query
        description: Threshold value to compare the selected metric against.
        required: true
        schema:
          oneOf:
          - type: number
            example: 10
          - type: integer
            example: 10
          - type: string
            example: '10'
      - name: comparedTo
        in: query
        description: 'Number of prior periods to compare against. Allowed values by period: day => 1, 7, 365; week => 1; month => 1, 12.'
        required: true
        schema:
          type: integer
          example: 1
      - name: reportUniqueId
        in: query
        description: Report unique ID in module_action format.
        required: true
        schema:
          type: string
          example: VisitsSummary_get
      - name: reportCondition
        in: query
        description: 'Optional dimension filter condition for report rows. Allowed values: matches_any, matches_exactly, does_not_match_exactly, matches_regex, does_not_match_regex, contains, does_not_contain, starts_with, does_not_start_with, ends_with, does_not_end_with.'
        required: false
        schema:
          type: string
      - name: reportValue
        in: query
        description: Value to match when $reportCondition is provided.
        required: false
        schema:
          type: string
      - name: reportMediums
        in: query
        description: 'Delivery channels to use for notifications. Allowed values: email, mobile, slack, teams.'
        required: false
        schema:
          type: array
          items: []
          default: []
      - name: slackChannelID
        in: query
        description: Slack channel ID when the slack channel is enabled.
        required: false
        schema:
          type: string
          default: ''
      - name: msTeamsWebhookUrl
        in: query
        description: Microsoft Teams webhook URL when the teams channel is enabled.
        required: false
        schema:
          type: string
          default: ''
      - name: description
        in: query
        description: Optional alert description (max 255 characters).
        required: false
        schema:
          type: string
          default: ''
      responses:
        '200':
          description: 'Updated alert ID.


            Example responses require Super User access. Use Try it out to see a live response.'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/DefaultError'
  /index.php?module=API&method=CustomAlerts.deleteAlert:
    get:
      tags:
      - CustomAlerts
      description: Deletes an existing custom alert.
      operationId: CustomAlerts.deleteAlert
      parameters:
      - $ref: '#/components/parameters/formatOptional'
      - name: idAlert
        in: query
        description: Alert ID to delete.
        required: true
        schema:
          type: integer
          example: 1
      responses:
        '200':
          $ref: '#/components/responses/GenericSuccess'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/DefaultError'
  /index.php?module=API&method=CustomAlerts.getTriggeredAlerts:
    get:
      tags:
      - CustomAlerts
      description: Returns triggered alerts for the current user and requested sites.
      operationId: CustomAlerts.getTriggeredAlerts
      parameters:
      - $ref: '#/components/parameters/formatOptional'
      - name: idSites
        in: query
        description: Website ID(s) to query. Accepts comma-separated IDs, "all", numeric IDs as strings, or ["all"].
        required: true
        schema:
          oneOf:
          - type: string
          - type: array
            items: []
        example: '[1,2]'
      responses:
        '200':
          description: 'Triggered alert entries for the current user and requested sites.


            Example responses require Super User access. Use Try it out to see a live response.'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/DefaultError'
components:
  schemas:
    GenericSuccessXml:
      description: Generic Matomo success payload in XML.
      required:
      - success
      properties:
        success:
          properties:
            message:
              type: string
              xml:
                attribute: true
              example: ok
          type: object
          xml:
            name: success
      type: object
      xml:
        name: result
      example:
        success:
          message: ok
      additionalProperties: true
    GenericSuccess:
      description: Generic Matomo success payload.
      required:
      - result
      - message
      properties:
        result:
          type: string
          example: success
        message:
          type: string
          example: ok
        code:
          type: integer
          example: '200'
      type: object
      example:
        result: success
        message: ok
      additionalProperties: true
    ErrorXml:
      description: Generic Matomo error payload in XML.
      properties:
        error:
          properties:
            message:
              type: string
              xml:
                attribute: true
              example: There was an error
          type: object
          xml:
            name: error
      type: object
      xml:
        name: result
    Error:
      description: Generic Matomo error payload.
      required:
      - result
      - message
      properties:
        result:
          type: string
          example: error
        message:
          type: string
          example: There was an error
        code:
          type: integer
      type: object
      additionalProperties: true
  responses:
    NotFound:
      description: Resource not found.
      content:
        text/plain:
          schema:
            type: string
          example: 'Error: The method is not available.'
        text/html:
          schema:
            type: string
          example: The method is not available.
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
        application/xml:
          schema:
            $ref: '#/components/schemas/ErrorXml'
    ServerError:
      description: Unexpected server error.
      content:
        text/plain:
          schema:
            type: string
          example: 'Error: There was an error.'
        text/html:
          schema:
            type: string
          example: There was an error.
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
        application/xml:
          schema:
            $ref: '#/components/schemas/ErrorXml'
    Unauthorized:
      description: Authentication failed or missing token.
      content:
        text/plain:
          schema:
            type: string
          example: 'Error: You must be logged in to access this functionality.'
        text/html:
          schema:
            type: string
          example: You must be logged in to access this functionality.
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
        application/xml:
          schema:
            $ref: '#/components/schemas/ErrorXml'
    Forbidden:
      description: Authenticated but not allowed to access the resource.
      content:
        text/plain:
          schema:
            type: string
          example: 'Error: Not authorised.'
        text/html:
          schema:
            type: string
          example: Not authorised.
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
        application/xml:
          schema:
            $ref: '#/components/schemas/ErrorXml'
    DefaultError:
      description: Default error response (any non-2xx).
      content:
        text/plain:
          schema:
            type: string
          example: 'Error: There was an error.'
        text/html:
          schema:
            type: string
          example: There was an error.
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
        application/xml:
          schema:
            $ref: '#/components/schemas/ErrorXml'
    GenericSuccess:
      description: Generic 200 response
      content:
        text/plain:
          schema:
            type: string
          example: Success:ok
        text/html:
          schema:
            type: string
          example: '<!-- Success: ok -->'
        application/json:
          schema:
            $ref: '#/components/schemas/GenericSuccess'
        application/xml:
          schema:
            $ref: '#/components/schemas/GenericSuccessXml'
    BadRequest:
      description: Bad request (validation or missing parameters).
      content:
        text/plain:
          schema:
            type: string
          example: 'Error: There was an error.'
        text/html:
          schema:
            type: string
          example: There was an error.
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
        application/xml:
          schema:
            $ref: '#/components/schemas/ErrorXml'
  parameters:
    formatOptional:
      name: format
      in: query
      description: Response format. Defaults to `xml`. Use `original` to get the original PHP data structure.
      required: false
      schema:
        type: string
        default: xml
        enum:
        - xml
        - json
        - csv
        - tsv
        - html
        - rss
        - original
  securitySchemes:
    MatomoToken:
      type: http
      description: Paste your token generated from Personal > Security. Swagger will send it as a Bearer token.
      scheme: bearer
externalDocs:
  description: Matomo Reporting API developer page
  url: https://developer.matomo.org/api-reference/reporting-api/