openapi: 3.2.0 info: title: Matomo Reporting API for plugin Form Analytics API version: 1.0.0 description: Exposes the Form Analytics API for managing tracked forms and retrieving form performance reports. Use these endpoints to create, update, archive, and delete configured forms, inspect form metadata, and query aggregated reports about form usage, field interactions, conversions, and real-time activity. servers: - url: https://demo-proxy.innocraft.cloud/ description: Current Matomo instance security: - MatomoToken: [] tags: - name: FormAnalytics description: Exposes the Form Analytics API for managing tracked forms and retrieving form performance reports. Use these endpoints to create, update, archive, and delete configured forms, inspect form metadata, and query aggregated reports about form usage, field interactions, conversions, and real-time activity. paths: /index.php?module=API&method=FormAnalytics.addForm: get: tags: - FormAnalytics description: Adds a new form to the specified website. operationId: FormAnalytics.addForm parameters: - $ref: '#/components/parameters/formatOptional' - name: idSite in: query description: The numeric ID of the website to configure. required: true schema: type: integer example: 1 - name: name in: query description: The form name shown in reports. required: true schema: type: string example: Pricing - name: description in: query description: Optional form description shown in reports. required: false schema: type: string default: '' - name: matchFormRules in: query description: 'Rules that decide which detected forms should be tracked into this configured form. Tracking starts when any rule matches a form. See "FormAnalytics.getAvailableFormRules" for the available rule definitions. Example: array(array(''attribute'' => ''form_name'', ''pattern'' => ''equals'', ''value'' => ''myformname''))' required: false schema: oneOf: - type: array items: type: string - type: string - name: matchPageRules in: query description: 'Rules that optionally restrict tracking to matching pages only. Tracking starts when any page rule matches. See "FormAnalytics.getAvailablePageRules" for the available rule definitions. Example: array(array(''attribute'' => ''path'', ''pattern'' => ''equals'', ''value'' => ''/sign-up''))' required: false schema: oneOf: - type: array items: type: string - type: string - name: conversionRuleOption in: query description: The conversion rule option to apply to this form. required: false schema: type: string default: page_visit - name: conversionRules in: query description: 'Rules that trigger a form conversion when a visitor matches one of the configured pages. See "FormAnalytics.getAvailablePageRules" for the available rule definitions. Example: array(array(''attribute'' => ''path'', ''pattern'' => ''equals'', ''value'' => ''/sign-up-success''))' required: false schema: oneOf: - type: array items: type: string - type: string - name: idGoal in: query description: Optional goal ID to trigger when the form converts. required: false schema: oneOf: - type: integer - type: string responses: '200': description: 'The created form 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=FormAnalytics.updateForm: get: tags: - FormAnalytics description: Updates an existing form. operationId: FormAnalytics.updateForm parameters: - $ref: '#/components/parameters/formatOptional' - name: idSite in: query description: The numeric ID of the website to configure. required: true schema: type: integer example: 1 - name: idForm in: query description: The numeric ID of the form to update. required: true schema: type: integer example: 1 - name: name in: query description: The form name shown in reports. required: true schema: type: string example: Pricing - name: description in: query description: Optional form description shown in reports. required: false schema: type: string default: '' - name: matchFormRules in: query description: 'Rules that decide which detected forms should be tracked into this configured form. Tracking starts when any rule matches a form. See "FormAnalytics.getAvailableFormRules" for the available rule definitions. Example: array(array(''attribute'' => ''form_name'', ''pattern'' => ''equals'', ''value'' => ''myformname''))' required: false schema: oneOf: - type: array items: type: string - type: string - name: matchPageRules in: query description: 'Rules that optionally restrict tracking to matching pages only. Tracking starts when any page rule matches. See "FormAnalytics.getAvailablePageRules" for the available rule definitions. Example: array(array(''attribute'' => ''path'', ''pattern'' => ''equals'', ''value'' => ''/sign-up''))' required: false schema: oneOf: - type: array items: type: string - type: string - name: conversionRuleOption in: query description: The conversion rule option to apply to this form. required: false schema: type: string default: page_visit - name: conversionRules in: query description: 'Rules that trigger a form conversion when a visitor matches one of the configured pages. See "FormAnalytics.getAvailablePageRules" for the available rule definitions. Example: array(array(''attribute'' => ''path'', ''pattern'' => ''equals'', ''value'' => ''/sign-up-success''))' required: false schema: oneOf: - type: array items: type: string - type: string - name: idGoal in: query description: Optional goal ID to trigger when the form converts. required: false schema: oneOf: - type: integer - type: string 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=FormAnalytics.getForm: get: tags: - FormAnalytics description: Get a specific form by its ID. operationId: FormAnalytics.getForm 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: idForm in: query description: The numeric ID of the form to fetch. required: true schema: type: integer example: 1 responses: '200': description: 'Form metadata, or false when the form does not exist. Expected keys: - idsiteform (int), idsite (int), name (string), description (string) - status (string), auto_created (bool), created_date (string), updated_date (string) - in_overview (int) - match_form_rules (array) - match_page_rules (array) - conversion_rule_option (string) - conversion_rules (array) - fields (array>), idgoal (int|null) 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=FormAnalytics.getForms: get: tags: - FormAnalytics description: Get all forms for a specific website or app. operationId: FormAnalytics.getForms 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 responses: '200': description: 'List of matching forms. Each form contains the same keys described in getForm(). Example responses require Super User access. Use Try it out to see a live response.' content: text/xml: [] application/json: [] '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=FormAnalytics.getFormsByStatuses: get: tags: - FormAnalytics description: Get a list of forms by status(es). To get a list of available statuses call "FormAnalytics.getAvailableStatuses". operationId: FormAnalytics.getFormsByStatuses 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: statuses in: query description: Status or list of statuses to fetch. required: true schema: oneOf: - type: string - type: array items: type: string example: '["running","finished"]' responses: '200': description: 'List of matching forms. Each form contains the same keys described in getForm(). Example responses require Super User access. Use Try it out to see a live response.' content: text/xml: [] application/json: [] '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=FormAnalytics.deleteForm: get: tags: - FormAnalytics description: Deletes the given form. operationId: FormAnalytics.deleteForm parameters: - $ref: '#/components/parameters/formatOptional' - name: idSite in: query description: The numeric ID of the website to configure. required: true schema: type: integer example: 1 - name: idForm in: query description: The numeric ID of the form 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=FormAnalytics.archiveForm: get: tags: - FormAnalytics description: Archives the given form. operationId: FormAnalytics.archiveForm parameters: - $ref: '#/components/parameters/formatOptional' - name: idSite in: query description: The numeric ID of the website to configure. required: true schema: type: integer example: 1 - name: idForm in: query description: The numeric ID of the form to archive. 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=FormAnalytics.get: get: tags: - FormAnalytics description: Get a form overview report. operationId: FormAnalytics.get 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: 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: idForm in: query description: Optional form ID to limit the overview to one form. Use `false` to aggregate all forms. required: false schema: oneOf: - type: integer - type: string - 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: columns in: query description: Optional metric names to include. Use `false` to return all metrics. required: false schema: oneOf: - type: string - type: array items: type: string responses: '200': description: 'Form overview metrics for all forms or for the requested form. 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=FormAnalytics.getSummary: get: tags: - FormAnalytics description: Get a per-form summary report for the selected period. operationId: FormAnalytics.getSummary 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: 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: columns in: query description: Optional metric names to include. Use `false` to return all metrics. required: false schema: oneOf: - type: string - type: array items: type: string responses: '200': description: 'Per-form overview metrics for all active and archived forms. 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=FormAnalytics.getEntryFields: get: tags: - FormAnalytics description: Get the entry fields report. operationId: FormAnalytics.getEntryFields 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: 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: idForm in: query description: The numeric ID of the form to query. required: true schema: type: integer example: 1 - 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: 'Report table containing entry field metrics and labels. 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=FormAnalytics.getDropOffFields: get: tags: - FormAnalytics description: Get the drop off fields report. operationId: FormAnalytics.getDropOffFields 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: 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: idForm in: query description: The numeric ID of the form to query. required: true schema: type: integer example: 1 - 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: 'Report table containing drop off metrics and labels. 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=FormAnalytics.getPageUrls: get: tags: - FormAnalytics description: Get form overview metrics for each page. This is useful when your form is embedded on several pages and you want to see how each form performs on the different pages. operationId: FormAnalytics.getPageUrls 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: 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: idForm in: query description: The numeric ID of the form to query. required: true schema: type: integer example: 1 - 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: 'Report table containing page URL metrics and labels. 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=FormAnalytics.getFieldTimings: get: tags: - FormAnalytics description: Get the field timings report to see how long visitors spent on each field or to see for how long they waited before they filled out a form field. operationId: FormAnalytics.getFieldTimings 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: 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: idForm in: query description: The numeric ID of the form to query. required: true schema: type: integer example: 1 - 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: 'Report table containing field timing metrics. 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=FormAnalytics.getFieldSize: get: tags: - FormAnalytics description: Get the field size report to see how many characters visitors typed into your text fields. operationId: FormAnalytics.getFieldSize 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: 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: idForm in: query description: The numeric ID of the form to query. required: true schema: type: integer example: 1 - 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: 'Report table containing field size metrics. 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=FormAnalytics.getUneededFields: get: tags: - FormAnalytics description: Get the unneeded fields report to see which fields were often left blank when your visitors submitted your forms. operationId: FormAnalytics.getUneededFields 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: 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: idForm in: query description: The numeric ID of the form to query. required: true schema: type: integer example: 1 - 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: 'Report table containing unneeded field metrics. 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=FormAnalytics.getMostUsedFields: get: tags: - FormAnalytics description: Get the most used fields to see which fields were most interacted and changed. operationId: FormAnalytics.getMostUsedFields 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: 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: idForm in: query description: The numeric ID of the form to query. required: true schema: type: integer example: 1 - 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: 'Report table containing most used field metrics. 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=FormAnalytics.getFieldCorrections: get: tags: - FormAnalytics description: Get the field corrections report to see which fields were corrected the most. For example backspaces, amendmends, refocuses, usage of cursors keys, etc. operationId: FormAnalytics.getFieldCorrections 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: 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: idForm in: query description: The numeric ID of the form to query. required: true schema: type: integer example: 1 - 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: 'Report table containing field correction metrics. 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=FormAnalytics.updateFormFieldDisplayName: get: tags: - FormAnalytics description: Lets you update known form fields to set a display name. operationId: FormAnalytics.updateFormFieldDisplayName parameters: - $ref: '#/components/parameters/formatOptional' - name: idSite in: query description: The numeric ID of the website to configure. required: true schema: type: integer example: 1 - name: idForm in: query description: The numeric ID of the form to update. required: true schema: type: integer example: 1 - name: fields in: query description: 'Field definitions to update, matched by field name. Example: array(array(''name'' => ''input1'', ''displayName'' => ''Email''))' required: false schema: type: array items: type: string default: [] 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=FormAnalytics.getCounters: get: tags: - FormAnalytics description: This method returns simple counters, for a given website ID, for visits over the last N minutes to see how your forms were doing in real time. operationId: FormAnalytics.getCounters 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: lastMinutes in: query description: Number of minutes to look back. required: true schema: type: integer example: 30 - 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: 'Real-time counters for form interactions. 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=FormAnalytics.getCurrentMostPopularForms: get: tags: - FormAnalytics description: This methods returns the currently most popular forms, for a given website ID, for visits over the last N minutes to see which forms are performing best in real time. operationId: FormAnalytics.getCurrentMostPopularForms 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: lastMinutes in: query description: Number of minutes to look back. required: true schema: type: integer example: 30 - name: filter_limit in: query description: Maximum number of rows to return. required: false schema: type: integer default: 5 - 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: 'Real-time list of the most popular forms. 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=FormAnalytics.getAutoCreationSettings: get: tags: - FormAnalytics description: Returns settings about the auto creation of forms. operationId: FormAnalytics.getAutoCreationSettings parameters: - $ref: '#/components/parameters/formatOptional' - name: idSite in: query description: The numeric ID of the website to configure. required: true schema: type: integer example: 1 responses: '200': description: 'UI message describing the current auto-creation configuration. 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=FormAnalytics.getAvailableStatuses: get: tags: - FormAnalytics description: Get a list of valid form statuses. operationId: FormAnalytics.getAvailableStatuses parameters: - $ref: '#/components/parameters/formatOptional' responses: '200': description: 'Available statuses with translated labels. 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=FormAnalytics.getAllGoals: get: tags: - FormAnalytics description: Get all goals configured for a site. operationId: FormAnalytics.getAllGoals 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 responses: '200': description: 'Map of goal IDs to goal names, plus an empty default option. 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=FormAnalytics.getAvailableFormRules: get: tags: - FormAnalytics description: Get a list of available form rule patterns that can be used to configure a form. operationId: FormAnalytics.getAvailableFormRules parameters: - $ref: '#/components/parameters/formatOptional' responses: '200': description: 'Available form rule definitions with translated labels, supported patterns, and examples. 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=FormAnalytics.getAvailablePageRules: get: tags: - FormAnalytics description: Get a list of available conversion rule patterns that can be used to configure a form. operationId: FormAnalytics.getAvailablePageRules parameters: - $ref: '#/components/parameters/formatOptional' responses: '200': description: 'Available page rule definitions with translated labels, supported patterns, and examples. 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=FormAnalytics.getAvailableConversionRuleOptions: get: tags: - FormAnalytics description: Get a list of available conversion rule options that can be used to configure a form. operationId: FormAnalytics.getAvailableConversionRuleOptions parameters: - $ref: '#/components/parameters/formatOptional' responses: '200': description: 'Map of conversion rule keys to translated labels. 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: '' 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/