openapi: 3.2.0
info:
  title: Matomo Reporting API for plugin Goals API
  version: 1.0.0
  description: 'Goals API lets you Manage existing goals, via "updateGoal" and "deleteGoal", create new Goals via "addGoal", or list existing Goals for one or several websites via "getGoals"  If you are <a href=''https://matomo.org/docs/ecommerce-analytics/'' target=''_blank''>tracking Ecommerce orders and products</a> on your site, the functions "getItemsSku", "getItemsName" and "getItemsCategory" will return the list of products purchased on your site, either grouped by Product SKU, Product Name or Product Category. For each name, SKU or category, the following metrics are returned: Total revenue, Total quantity, average price, average quantity, number of orders (or abandoned carts) containing this product, number of visits on the Product page, Conversion rate.  By default, these functions return the ''Products purchased''. These functions also accept an optional parameter &abandonedCarts=1. If the parameter is set, it will instead return the metrics for products that were left in an abandoned cart therefore not purchased.  The API also lets you request overall Goal metrics via the method "get": Conversions, Visits with at least one conversion, Conversion rate and Revenue. If you wish to request specific metrics about Ecommerce goals, you can set the parameter &idGoal=ecommerceAbandonedCart to get metrics about abandoned carts (including Lost revenue, and number of items left in the cart) or &idGoal=ecommerceOrder to get metrics about Ecommerce orders (number of orders, visits with an order, subtotal, tax, shipping, discount, revenue, items ordered)  See also the documentation about <a href=''https://matomo.org/docs/tracking-goals-web-analytics/'' rel=''noreferrer'' target=''_blank''>Tracking Goals</a> in Matomo.'
servers:
- url: https://demo-proxy.innocraft.cloud/
  description: Current Matomo instance
security:
- MatomoToken: []
tags:
- name: Goals
  description: 'Goals API lets you Manage existing goals, via "updateGoal" and "deleteGoal", create new Goals via "addGoal", or list existing Goals for one or several websites via "getGoals"  If you are <a href=''https://matomo.org/docs/ecommerce-analytics/'' target=''_blank''>tracking Ecommerce orders and products</a> on your site, the functions "getItemsSku", "getItemsName" and "getItemsCategory" will return the list of products purchased on your site, either grouped by Product SKU, Product Name or Product Category. For each name, SKU or category, the following metrics are returned: Total revenue, Total quantity, average price, average quantity, number of orders (or abandoned carts) containing this product, number of visits on the Product page, Conversion rate.  By default, these functions return the ''Products purchased''. These functions also accept an optional parameter &abandonedCarts=1. If the parameter is set, it will instead return the metrics for products that were left in an abandoned cart therefore not purchased.  The API also lets you request overall Goal metrics via the method "get": Conversions, Visits with at least one conversion, Conversion rate and Revenue. If you wish to request specific metrics about Ecommerce goals, you can set the parameter &idGoal=ecommerceAbandonedCart to get metrics about abandoned carts (including Lost revenue, and number of items left in the cart) or &idGoal=ecommerceOrder to get metrics about Ecommerce orders (number of orders, visits with an order, subtotal, tax, shipping, discount, revenue, items ordered)  See also the documentation about <a href=''https://matomo.org/docs/tracking-goals-web-analytics/'' rel=''noreferrer'' target=''_blank''>Tracking Goals</a> in Matomo.'
paths:
  /index.php?module=API&method=Goals.getGoal:
    get:
      tags:
      - Goals
      description: Return a single goal.
      operationId: Goals.getGoal
      parameters:
      - $ref: '#/components/parameters/formatOptional'
      - name: idSite
        in: query
        description: The numeric ID of the website to query.
        required: true
        schema:
          type: integer
          example: 1
      - name: idGoal
        in: query
        description: The numeric ID of the goal to query.
        required: true
        schema:
          type: integer
          example: 1
      responses:
        '200':
          description: 'Goal attributes, or `null` if the goal does not exist.


            Example responses require Super User access. Use Try it out to see a live response.'
          content:
            text/xml: []
            application/json: []
            application/vnd.ms-excel: []
        '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=Goals.getGoals:
    get:
      tags:
      - Goals
      description: Returns all goals for one or more websites.
      operationId: Goals.getGoals
      parameters:
      - $ref: '#/components/parameters/formatOptional'
      - name: idSite
        in: query
        description: Website ID(s) to query. - Single site ID (e.g. 1) - Multiple site IDs (e.g. [1, 4, 5]) - Comma-separated list ("1,4,5") or "all"
        required: true
        schema:
          oneOf:
          - type: integer
            example: 1
          - type: string
            example: '1'
          - type: array
            items:
              type: integer
            example: 1
      - name: orderByName
        in: query
        description: Whether to sort the returned goals alphabetically by name.
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: 'Goal attributes, indexed by goal ID for single-site requests and returned as a numeric list for multi-site requests.


            Example responses require Super User access. Use Try it out to see a live response.'
          content:
            text/xml: []
            application/json: []
            application/vnd.ms-excel: []
        '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=Goals.addGoal:
    get:
      tags:
      - Goals
      description: Creates a goal for a website.
      operationId: Goals.addGoal
      parameters:
      - $ref: '#/components/parameters/formatOptional'
      - name: idSite
        in: query
        description: The numeric ID of the website to configure the goal for.
        required: true
        schema:
          type: integer
          example: 1
      - name: name
        in: query
        description: Goal name.
        required: true
        schema:
          type: string
          example: Pricing
      - name: matchAttribute
        in: query
        description: Attribute used to match conversions.
        required: true
        schema:
          type: string
          example: url
      - name: pattern
        in: query
        description: Match pattern. Use a URL, title, filename, external website, or event value for string match attributes; use a numeric threshold for visit duration, actions, or pageview match attributes; this value is ignored for `manually`.
        required: true
        schema:
          type: string
          example: https://example.org/pricing
      - name: patternType
        in: query
        description: Matching operator. Numeric match attributes only accept `greater_than`; string match attributes accept `exact`, `contains`, or `regex`; use an empty string for `manually`.
        required: true
        schema:
          type: string
          example: equals
      - name: caseSensitive
        in: query
        description: Whether string matching should be case-sensitive.
        required: false
        schema:
          type: boolean
          default: false
      - name: revenue
        in: query
        description: Default revenue to assign to conversions. Pass `false` or `0` to disable a fixed revenue value.
        required: false
        schema:
          type: number
      - name: allowMultipleConversionsPerVisit
        in: query
        description: Whether multiple conversions may be recorded within one visit.
        required: false
        schema:
          type: boolean
          default: false
      - name: description
        in: query
        description: Optional goal description shown in the Goals management UI.
        required: false
        schema:
          type: string
          default: ''
      - name: useEventValueAsRevenue
        in: query
        description: Whether to use the tracked event value as goal revenue. This is only valid for event-based goals.
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: 'ID of the new goal.


            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=Goals.updateGoal:
    get:
      tags:
      - Goals
      description: Updates an existing goal without reprocessing already recorded conversions.
      operationId: Goals.updateGoal
      parameters:
      - $ref: '#/components/parameters/formatOptional'
      - name: idSite
        in: query
        description: The numeric ID of the website the goal belongs to.
        required: true
        schema:
          type: integer
          example: 1
      - name: idGoal
        in: query
        description: Goal ID to update.
        required: true
        schema:
          type: integer
          example: 1
      - name: name
        in: query
        description: Goal name.
        required: true
        schema:
          type: string
          example: Pricing
      - name: matchAttribute
        in: query
        description: Attribute used to match conversions.
        required: true
        schema:
          type: string
          example: url
      - name: pattern
        in: query
        description: Match pattern. Use a URL, title, filename, external website, or event value for string match attributes; use a numeric threshold for visit duration, actions, or pageview match attributes; this value is ignored for `manually`.
        required: true
        schema:
          type: string
          example: https://example.org/pricing
      - name: patternType
        in: query
        description: Matching operator. Numeric match attributes only accept `greater_than`; string match attributes accept `exact`, `contains`, or `regex`; use an empty string for `manually`.
        required: true
        schema:
          type: string
          example: equals
      - name: caseSensitive
        in: query
        description: Whether string matching should be case-sensitive.
        required: false
        schema:
          type: boolean
          default: false
      - name: revenue
        in: query
        description: Default revenue to assign to conversions. Pass `false` or `0` to disable a fixed revenue value.
        required: false
        schema:
          type: number
      - name: allowMultipleConversionsPerVisit
        in: query
        description: Whether multiple conversions may be recorded within one visit.
        required: false
        schema:
          type: boolean
          default: false
      - name: description
        in: query
        description: Optional goal description shown in the Goals management UI.
        required: false
        schema:
          type: string
          default: ''
      - name: useEventValueAsRevenue
        in: query
        description: Whether to use the tracked event value as goal revenue. This is only valid for event-based goals.
        required: false
        schema:
          type: boolean
          default: false
      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=Goals.deleteGoal:
    get:
      tags:
      - Goals
      description: Soft deletes a given Goal.
      operationId: Goals.deleteGoal
      parameters:
      - $ref: '#/components/parameters/formatOptional'
      - name: idSite
        in: query
        description: The numeric ID of the website to query.
        required: true
        schema:
          type: integer
          example: 1
      - name: idGoal
        in: query
        description: The numeric ID of the goal 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=Goals.getItemsSku:
    get:
      tags:
      - Goals
      description: Returns ecommerce product metrics grouped by product SKU.
      operationId: Goals.getItemsSku
      parameters:
      - $ref: '#/components/parameters/formatOptional'
      - name: idSite
        in: query
        description: Website ID(s) to query. - Single site ID (e.g. 1) - Multiple site IDs (e.g. [1, 4, 5]) - Comma-separated list ("1,4,5") or "all"
        required: true
        schema:
          oneOf:
          - type: integer
            example: 1
          - type: string
            example: '1'
          - type: array
            items:
              type: integer
            example: 1
      - name: period
        in: query
        description: The period to process, processes data for the period containing the specified date.
        required: true
        schema:
          type: string
          enum:
          - day
          - week
          - month
          - year
          - range
          example: day
      - name: date
        in: query
        description: The date or date range to process. 'YYYY-MM-DD', magic keywords (today, yesterday, lastWeek, lastMonth, lastYear), or date range (ie, 'YYYY-MM-DD,YYYY-MM-DD', lastX, previousX).
        required: true
        schema:
          type: string
          example: yesterday
      - name: abandonedCarts
        in: query
        description: Whether to return abandoned-cart product metrics instead of purchased products.
        required: false
        schema:
          type: boolean
          default: false
      - name: segment
        in: query
        description: 'Custom segment to filter the report. Example: "referrerName==example.com" Supports AND (;) and OR (,) operators.'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: 'Ecommerce product metrics grouped by SKU.


            Example responses require Super User access. Use Try it out to see a live response.'
          content:
            text/xml: []
            application/json: []
            application/vnd.ms-excel: []
        '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=Goals.getItemsName:
    get:
      tags:
      - Goals
      description: Returns ecommerce product metrics grouped by product name.
      operationId: Goals.getItemsName
      parameters:
      - $ref: '#/components/parameters/formatOptional'
      - name: idSite
        in: query
        description: Website ID(s) to query. - Single site ID (e.g. 1) - Multiple site IDs (e.g. [1, 4, 5]) - Comma-separated list ("1,4,5") or "all"
        required: true
        schema:
          oneOf:
          - type: integer
            example: 1
          - type: string
            example: '1'
          - type: array
            items:
              type: integer
            example: 1
      - name: period
        in: query
        description: The period to process, processes data for the period containing the specified date.
        required: true
        schema:
          type: string
          enum:
          - day
          - week
          - month
          - year
          - range
          example: day
      - name: date
        in: query
        description: The date or date range to process. 'YYYY-MM-DD', magic keywords (today, yesterday, lastWeek, lastMonth, lastYear), or date range (ie, 'YYYY-MM-DD,YYYY-MM-DD', lastX, previousX).
        required: true
        schema:
          type: string
          example: yesterday
      - name: abandonedCarts
        in: query
        description: Whether to return abandoned-cart product metrics instead of purchased products.
        required: false
        schema:
          type: boolean
          default: false
      - name: segment
        in: query
        description: 'Custom segment to filter the report. Example: "referrerName==example.com" Supports AND (;) and OR (,) operators.'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: 'Ecommerce product metrics grouped by name.


            Example responses require Super User access. Use Try it out to see a live response.'
          content:
            text/xml: []
            application/json: []
            application/vnd.ms-excel: []
        '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=Goals.getItemsCategory:
    get:
      tags:
      - Goals
      description: Returns ecommerce product metrics grouped by product category.
      operationId: Goals.getItemsCategory
      parameters:
      - $ref: '#/components/parameters/formatOptional'
      - name: idSite
        in: query
        description: Website ID(s) to query. - Single site ID (e.g. 1) - Multiple site IDs (e.g. [1, 4, 5]) - Comma-separated list ("1,4,5") or "all"
        required: true
        schema:
          oneOf:
          - type: integer
            example: 1
          - type: string
            example: '1'
          - type: array
            items:
              type: integer
            example: 1
      - name: period
        in: query
        description: The period to process, processes data for the period containing the specified date.
        required: true
        schema:
          type: string
          enum:
          - day
          - week
          - month
          - year
          - range
          example: day
      - name: date
        in: query
        description: The date or date range to process. 'YYYY-MM-DD', magic keywords (today, yesterday, lastWeek, lastMonth, lastYear), or date range (ie, 'YYYY-MM-DD,YYYY-MM-DD', lastX, previousX).
        required: true
        schema:
          type: string
          example: yesterday
      - name: abandonedCarts
        in: query
        description: Whether to return abandoned-cart product metrics instead of purchased products.
        required: false
        schema:
          type: boolean
          default: false
      - name: segment
        in: query
        description: 'Custom segment to filter the report. Example: "referrerName==example.com" Supports AND (;) and OR (,) operators.'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: 'Ecommerce product metrics grouped by category.


            Example responses require Super User access. Use Try it out to see a live response.'
          content:
            text/xml: []
            application/json: []
            application/vnd.ms-excel: []
        '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=Goals.get:
    get:
      tags:
      - Goals
      description: Returns goal and ecommerce metrics, including new and returning visitor variants.
      operationId: Goals.get
      parameters:
      - $ref: '#/components/parameters/formatOptional'
      - name: idSite
        in: query
        description: Website ID(s) to query. - Single site ID (e.g. 1) - Multiple site IDs (e.g. [1, 4, 5]) - Comma-separated list ("1,4,5") or "all"
        required: true
        schema:
          oneOf:
          - type: integer
            example: 1
          - type: string
            example: '1'
          - type: array
            items:
              type: integer
            example: 1
      - name: period
        in: query
        description: The period to process, processes data for the period containing the specified date.
        required: true
        schema:
          type: string
          enum:
          - day
          - week
          - month
          - year
          - range
          example: day
      - name: date
        in: query
        description: The date or date range to process. 'YYYY-MM-DD', magic keywords (today, yesterday, lastWeek, lastMonth, lastYear), or date range (ie, 'YYYY-MM-DD,YYYY-MM-DD', lastX, previousX).
        required: true
        schema:
          type: string
          example: yesterday
      - name: segment
        in: query
        description: 'Custom segment to filter the report. Example: "referrerName==example.com" Supports AND (;) and OR (,) operators.'
        required: false
        schema:
          type: string
      - name: idGoal
        in: query
        description: Goal ID, `ecommerceOrder`, `ecommerceAbandonedCart`, or `false` for all goals.
        required: false
        schema:
          oneOf:
          - type: integer
          - type: string
      - name: columns
        in: query
        description: Optional metric name or list of metric names to return, for example `nb_conversions`, `nb_visits_converted`, `conversion_rate`, `revenue`, or ecommerce-specific metrics such as `items` or `avg_order_revenue`.
        required: false
        schema:
          oneOf:
          - type: string
            default: '[]'
          - type: array
            items:
              type: string
            default: []
      - name: showAllGoalSpecificMetrics
        in: query
        description: Whether to include per-goal metric columns when no specific goal is selected.
        required: false
        schema:
          type: boolean
          default: false
      - name: compare
        in: query
        description: Whether to prepare the table for a comparison report by deferring metric formatting.
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: 'Goal metrics with additional columns for all visits, new visits, and returning visits.


            Example responses require Super User access. Use Try it out to see a live response.'
          content:
            text/xml: []
            application/json: []
            application/vnd.ms-excel: []
        '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=Goals.getDaysToConversion:
    get:
      tags:
      - Goals
      description: Returns conversions grouped by the number of days between first visit and conversion.
      operationId: Goals.getDaysToConversion
      parameters:
      - $ref: '#/components/parameters/formatOptional'
      - name: idSite
        in: query
        description: Website ID(s) to query. - Single site ID (e.g. 1) - Multiple site IDs (e.g. [1, 4, 5]) - Comma-separated list ("1,4,5") or "all"
        required: true
        schema:
          oneOf:
          - type: integer
            example: 1
          - type: string
            example: '1'
          - type: array
            items:
              type: integer
            example: 1
      - name: period
        in: query
        description: The period to process, processes data for the period containing the specified date.
        required: true
        schema:
          type: string
          enum:
          - day
          - week
          - month
          - year
          - range
          example: day
      - name: date
        in: query
        description: The date or date range to process. 'YYYY-MM-DD', magic keywords (today, yesterday, lastWeek, lastMonth, lastYear), or date range (ie, 'YYYY-MM-DD,YYYY-MM-DD', lastX, previousX).
        required: true
        schema:
          type: string
          example: yesterday
      - name: segment
        in: query
        description: 'Custom segment to filter the report. Example: "referrerName==example.com" Supports AND (;) and OR (,) operators.'
        required: false
        schema:
          type: string
      - name: idGoal
        in: query
        description: Goal ID, `ecommerceOrder`, `ecommerceAbandonedCart`, or `false` for all goals.
        required: false
        schema:
          oneOf:
          - type: integer
          - type: string
      responses:
        '200':
          description: 'Conversion counts grouped by days until conversion.


            Example responses require Super User access. Use Try it out to see a live response.'
          content:
            text/xml: []
            application/json: []
            application/vnd.ms-excel: []
        '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=Goals.getVisitsUntilConversion:
    get:
      tags:
      - Goals
      description: Returns conversions grouped by the visit count before conversion.
      operationId: Goals.getVisitsUntilConversion
      parameters:
      - $ref: '#/components/parameters/formatOptional'
      - name: idSite
        in: query
        description: Website ID(s) to query. - Single site ID (e.g. 1) - Multiple site IDs (e.g. [1, 4, 5]) - Comma-separated list ("1,4,5") or "all"
        required: true
        schema:
          oneOf:
          - type: integer
            example: 1
          - type: string
            example: '1'
          - type: array
            items:
              type: integer
            example: 1
      - name: period
        in: query
        description: The period to process, processes data for the period containing the specified date.
        required: true
        schema:
          type: string
          enum:
          - day
          - week
          - month
          - year
          - range
          example: day
      - name: date
        in: query
        description: The date or date range to process. 'YYYY-MM-DD', magic keywords (today, yesterday, lastWeek, lastMonth, lastYear), or date range (ie, 'YYYY-MM-DD,YYYY-MM-DD', lastX, previousX).
        required: true
        schema:
          type: string
          example: yesterday
      - name: segment
        in: query
        description: 'Custom segment to filter the report. Example: "referrerName==example.com" Supports AND (;) and OR (,) operators.'
        required: false
        schema:
          type: string
      - name: idGoal
        in: query
        description: Goal ID, `ecommerceOrder`, `ecommerceAbandonedCart`, or `false` for all goals.
        required: false
        schema:
          oneOf:
          - type: integer
          - type: string
      responses:
        '200':
          description: 'Conversion counts grouped by visits until conversion.


            Example responses require Super User access. Use Try it out to see a live response.'
          content:
            text/xml: []
            application/json: []
            application/vnd.ms-excel: []
        '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/