openapi: 3.2.0
info:
title: Matomo Reporting API for plugin Sites Manager API
version: 1.0.0
description: 'The SitesManager API gives you full control on Websites in Matomo (create, update and delete), and many methods to retrieve websites based on various attributes. This API lets you create websites via "addSite", update existing websites via "updateSite" and delete websites via "deleteSite". When creating websites, it can be useful to access internal codes used by Matomo for currencies via "getCurrencyList", or timezones via "getTimezonesList". There are also many ways to request a list of websites: from the website ID via "getSiteFromId" or the site URL via "getSitesIdFromSiteUrl". Often, the most useful technique is to list all websites that are known to a current user, based on the token_auth, via "getSitesWithAdminAccess", "getSitesWithViewAccess" or "getSitesWithAtLeastViewAccess" (which returns both). Some methods will affect all websites globally: "setGlobalExcludedIps" will set the list of IPs to be excluded on all websites, "setGlobalExcludedQueryParameters" will set the list of URL parameters to remove from URLs for all websites. The existing values can be fetched via "getExcludedIpsGlobal" and "getExcludedQueryParametersGlobal". See also the documentation about Managing Websites in Matomo.'
servers:
- url: https://demo-proxy.innocraft.cloud/
description: Current Matomo instance
security:
- MatomoToken: []
tags:
- name: SitesManager
description: 'The SitesManager API gives you full control on Websites in Matomo (create, update and delete), and many methods to retrieve websites based on various attributes. This API lets you create websites via "addSite", update existing websites via "updateSite" and delete websites via "deleteSite". When creating websites, it can be useful to access internal codes used by Matomo for currencies via "getCurrencyList", or timezones via "getTimezonesList". There are also many ways to request a list of websites: from the website ID via "getSiteFromId" or the site URL via "getSitesIdFromSiteUrl". Often, the most useful technique is to list all websites that are known to a current user, based on the token_auth, via "getSitesWithAdminAccess", "getSitesWithViewAccess" or "getSitesWithAtLeastViewAccess" (which returns both). Some methods will affect all websites globally: "setGlobalExcludedIps" will set the list of IPs to be excluded on all websites, "setGlobalExcludedQueryParameters" will set the list of URL parameters to remove from URLs for all websites. The existing values can be fetched via "getExcludedIpsGlobal" and "getExcludedQueryParametersGlobal". See also the documentation about Managing Websites in Matomo.'
paths:
/index.php?module=API&method=SitesManager.getJavascriptTag:
get:
tags:
- SitesManager
description: Returns the JavaScript tracking tag for the given website.
operationId: SitesManager.getJavascriptTag
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: idSite
in: query
description: The numeric ID of the website to generate tracking code for.
required: true
schema:
type: integer
example: 1
- name: piwikUrl
in: query
description: The domain and URL path to the Matomo installation. Defaults to the current Matomo URL.
required: false
schema:
type: string
default: ''
- name: mergeSubdomains
in: query
description: Whether to track visitors across all subdomains of the site.
required: false
schema:
type: boolean
default: false
- name: groupPageTitlesByDomain
in: query
description: Whether to prepend the site domain to the page title when tracking.
required: false
schema:
type: boolean
default: false
- name: mergeAliasUrls
in: query
description: Whether to treat alias URLs as part of the same website for outlink detection.
required: false
schema:
type: boolean
default: false
- name: visitorCustomVariables
in: query
description: Custom visitor-scope variables as `array(array('name', 'value'), ...)`.
required: false
schema:
type: array
items:
type: string
default: []
- name: pageCustomVariables
in: query
description: Custom page-scope variables as `array(array('name', 'value'), ...)`.
required: false
schema:
type: array
items:
type: string
default: []
- name: customCampaignNameQueryParam
in: query
description: Custom campaign name query parameter name, overriding the default.
required: false
schema:
type: string
default: ''
- name: customCampaignKeywordParam
in: query
description: Custom campaign keyword query parameter name, overriding the default.
required: false
schema:
type: string
default: ''
- name: doNotTrack
in: query
description: Whether to respect the browser's Do-Not-Track setting.
required: false
schema:
type: boolean
default: false
- name: disableCookies
in: query
description: Whether to disable all first-party cookies.
required: false
schema:
type: boolean
default: false
- name: trackNoScript
in: query
description: Whether to include a `` image-based fallback for JavaScript-disabled browsers.
required: false
schema:
type: boolean
default: false
- name: crossDomain
in: query
description: Whether to enable cross-domain linking.
required: false
schema:
type: boolean
default: false
- name: forceMatomoEndpoint
in: query
description: Whether the Matomo endpoint should be forced if Matomo was installed prior to 3.7.0.
required: false
schema:
type: boolean
default: false
- name: excludedQueryParams
in: query
description: Array or comma-separated string of query parameters to exclude from page URLs.
required: false
schema:
oneOf:
- type: string
default: ''
- type: array
items:
type: string
- name: excludedReferrers
in: query
description: Array or comma-separated string of referrer hosts/URLs to ignore.
required: false
schema:
oneOf:
- type: string
default: ''
- type: array
items:
type: string
- name: disableCampaignParameters
in: query
description: Whether to prevent campaign parameters from being sent to the tracker.
required: false
schema:
type: boolean
default: false
responses:
'200':
description: 'The JavaScript tag ready to be included in HTML pages.
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=SitesManager.getImageTrackingCode:
get:
tags:
- SitesManager
description: Returns image link tracking code for a given site with specified options.
operationId: SitesManager.getImageTrackingCode
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: idSite
in: query
description: The ID to generate tracking code for.
required: true
schema:
type: integer
example: 1
- name: piwikUrl
in: query
description: The domain and URL path to the Matomo installation.
required: false
schema:
type: string
default: ''
- name: actionName
in: query
description: Action name to include in the image tracking request, or `false` to omit it.
required: false
schema:
type: string
- name: idGoal
in: query
description: Goal ID to trigger a conversion for, or `false` to omit goal tracking.
required: false
schema:
oneOf:
- type: integer
- type: string
- name: revenue
in: query
description: Revenue for the goal conversion. Only used when `$idGoal` is supplied.
required: false
schema:
oneOf:
- type: integer
- type: number
- type: string
- name: forceMatomoEndpoint
in: query
description: Whether the Matomo endpoint should be forced if Matomo was installed prior to 3.7.0.
required: false
schema:
type: boolean
default: false
responses:
'200':
description: 'The HTML-encoded image tracking code.
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=SitesManager.getSitesFromGroup:
get:
tags:
- SitesManager
description: Returns all websites belonging to the specified group.
operationId: SitesManager.getSitesFromGroup
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: group
in: query
description: Group name to filter by. An empty string returns websites without a group.
required: false
schema:
type: string
default: ''
responses:
'200':
description: 'Websites belonging to the group.
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=SitesManager.getSitesGroups:
get:
tags:
- SitesManager
description: Returns the list of website groups, including the empty group if no group was specified for some websites.
operationId: SitesManager.getSitesGroups
parameters:
- $ref: '#/components/parameters/formatOptional'
responses:
'200':
description: 'Distinct group names.
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=SitesManager.getSiteFromId:
get:
tags:
- SitesManager
description: 'Returns the website information for a single site: name, main_url, timezone, currency, etc.'
operationId: SitesManager.getSiteFromId
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: idSite
in: query
description: The numeric ID of the website.
required: true
schema:
type: integer
example: 1
responses:
'200':
description: 'Site data array.
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=SitesManager.getSiteUrlsFromId:
get:
tags:
- SitesManager
description: Returns the list of all URLs registered for the given website (main_url + alias URLs).
operationId: SitesManager.getSiteUrlsFromId
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: idSite
in: query
description: The numeric ID of the website.
required: true
schema:
type: integer
example: 1
responses:
'200':
description: 'List of URLs, with the main URL first.
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=SitesManager.getAllSites:
get:
tags:
- SitesManager
description: Returns all websites.
operationId: SitesManager.getAllSites
parameters:
- $ref: '#/components/parameters/formatOptional'
responses:
'200':
description: 'The list of websites, indexed by idsite.
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=SitesManager.getAllSitesId:
get:
tags:
- SitesManager
description: Returns the list of all the website IDs registered.
operationId: SitesManager.getAllSitesId
parameters:
- $ref: '#/components/parameters/formatOptional'
responses:
'200':
description: 'The list of website 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=SitesManager.getSitesWithAdminAccess:
get:
tags:
- SitesManager
description: Returns the list of websites with the 'admin' access for the current user.
operationId: SitesManager.getSitesWithAdminAccess
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: fetchAliasUrls
in: query
description: Whether to include alias URLs as an `alias_urls` key in each site entry.
required: false
schema:
type: boolean
default: false
- name: pattern
in: query
description: Optional name/URL pattern to filter results by.
required: false
schema:
type: string
- name: limit
in: query
description: Maximum number of sites to return, or `false` for no limit.
required: false
schema:
oneOf:
- type: integer
- type: string
- name: sitesToExclude
in: query
description: Site IDs to exclude from the result.
required: false
schema:
type: array
items:
type: integer
default: []
responses:
'200':
description: 'Websites the current user has admin access to.
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=SitesManager.getSitesWithMinimumAccess:
get:
tags:
- SitesManager
description: Returns the list of websites where the current user has at least the provided access level.
operationId: SitesManager.getSitesWithMinimumAccess
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: permission
in: query
description: One of `'view'`, `'write'` or `'admin'`.
required: true
schema:
type: string
example: view
- name: pattern
in: query
description: Optional name/URL pattern to filter results by.
required: false
schema:
type: string
- name: limit
in: query
description: Maximum number of sites to return, or `null` for no limit.
required: false
schema:
type: integer
- name: sitesToExclude
in: query
description: Site IDs to exclude from the result.
required: false
schema:
type: array
items:
type: integer
default: []
- name: siteTypesToExclude
in: query
description: Site types (e.g. `'website'`, `'mobileapp'`) to exclude from the result.
required: false
schema:
type: array
items:
type: string
default: []
responses:
'200':
description: 'Websites matching the access level and filters.
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=SitesManager.getSitesWithViewAccess:
get:
tags:
- SitesManager
description: Returns the list of websites with the 'view' access for the current user.
operationId: SitesManager.getSitesWithViewAccess
parameters:
- $ref: '#/components/parameters/formatOptional'
responses:
'200':
description: 'Websites the current user has view-only access to.
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=SitesManager.getSitesWithAtLeastViewAccess:
get:
tags:
- SitesManager
description: Returns the list of websites with the 'view' or 'admin' access for the current user.
operationId: SitesManager.getSitesWithAtLeastViewAccess
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: limit
in: query
description: Maximum number of sites to return, or `false` for no limit.
required: false
schema:
oneOf:
- type: integer
- type: string
- name: _restrictSitesToLogin
in: query
description: 'Implementation detail for scheduled tasks where Superuser access is forced but sites should be restricted to a specific login. See #3017.'
required: false
schema:
type: string
responses:
'200':
description: 'Websites the current user has at least view access to.
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=SitesManager.getSitesIdWithAdminAccess:
get:
tags:
- SitesManager
description: Returns the list of website IDs with the 'admin' access for the current user.
operationId: SitesManager.getSitesIdWithAdminAccess
parameters:
- $ref: '#/components/parameters/formatOptional'
responses:
'200':
description: 'Website 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=SitesManager.getSitesIdWithViewAccess:
get:
tags:
- SitesManager
description: Returns the list of website IDs with the 'view' access for the current user.
operationId: SitesManager.getSitesIdWithViewAccess
parameters:
- $ref: '#/components/parameters/formatOptional'
responses:
'200':
description: 'Website IDs.
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=SitesManager.getSitesIdWithWriteAccess:
get:
tags:
- SitesManager
description: Returns the list of website IDs with the 'write' access for the current user.
operationId: SitesManager.getSitesIdWithWriteAccess
parameters:
- $ref: '#/components/parameters/formatOptional'
responses:
'200':
description: 'Website 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=SitesManager.getSitesIdWithAtLeastViewAccess:
get:
tags:
- SitesManager
description: Returns the list of website IDs with the 'view' or 'admin' access for the current user.
operationId: SitesManager.getSitesIdWithAtLeastViewAccess
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: _restrictSitesToLogin
in: query
description: Implementation detail for scheduled tasks where Superuser access is forced but sites should be restricted to a specific login.
required: false
schema:
type: string
responses:
'200':
description: 'Website IDs.
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=SitesManager.getSitesIdFromSiteUrl:
get:
tags:
- SitesManager
description: Returns the list of website IDs associated with a URL.
operationId: SitesManager.getSitesIdFromSiteUrl
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: url
in: query
description: The URL to search for.
required: true
schema:
type: string
example: https://example.org/pricing
responses:
'200':
description: 'Matching website IDs.
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=SitesManager.addSite:
get:
tags:
- SitesManager
description: Add a website.
operationId: SitesManager.addSite
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: siteName
in: query
description: Site name.
required: true
schema:
type: string
example: Example NZ Site
- name: urls
in: query
description: The URLs array must contain at least one URL called the 'main_url'; if several URLs are provided in the array, they will be recorded as alias URLs for this website. When calling the API via HTTP specify multiple URLs via `&urls[]=http...&urls[]=http...`.
required: false
schema:
oneOf:
- type: array
items:
type: string
- type: string
- name: ecommerce
in: query
description: Whether Ecommerce Reporting is enabled (1) or disabled (0).
required: false
schema:
oneOf:
- type: integer
- type: string
- name: siteSearch
in: query
description: Whether Site Search is enabled (1) or disabled (0).
required: false
schema:
oneOf:
- type: integer
- type: string
- name: searchKeywordParameters
in: query
description: Comma-separated list of search keyword parameter names.
required: false
schema:
type: string
- name: searchCategoryParameters
in: query
description: Comma-separated list of search category parameter names.
required: false
schema:
type: string
- name: excludedIps
in: query
description: Comma-separated list of IPs to exclude from reports (allows wildcards).
required: false
schema:
type: string
- name: excludedQueryParameters
in: query
description: Comma-separated list of URL query parameters to strip from tracked URLs.
required: false
schema:
type: string
- name: timezone
in: query
description: Timezone string, e.g. `'Europe/London'`. Defaults to the global default timezone.
required: false
schema:
type: string
- name: currency
in: query
description: Currency code, e.g. `'EUR'`. Defaults to the global default currency.
required: false
schema:
type: string
- name: group
in: query
description: Website group identifier. Requires Superuser access.
required: false
schema:
type: string
- name: startDate
in: query
description: Date at which statistics for this website will start, in `YYYY-MM-DD` format. Defaults to today's date.
required: false
schema:
type: string
- name: excludedUserAgents
in: query
description: Comma-separated list of user agent substrings to exclude.
required: false
schema:
type: string
- name: keepURLFragments
in: query
description: If `1`, URL fragments will be kept when tracking. If `2`, they will be removed. If `0`, the default global behavior will be used.
required: false
schema:
oneOf:
- type: integer
- type: string
- name: type
in: query
description: The website type, defaults to `'website'` if not set.
required: false
schema:
type: string
- name: settingValues
in: query
description: Measurable settings keyed by plugin name, each containing an array of `['name' => string, 'value' => mixed]` pairs.
required: false
schema:
type: string
- name: excludeUnknownUrls
in: query
description: Whether to track only URLs matching one of the website's registered URLs.
required: false
schema:
type: string
- name: excludedReferrers
in: query
description: Comma-separated list of hosts/URLs to exclude from referrer detection.
required: false
schema:
type: string
- name: description
in: query
description: Optional description providing additional context about this site, such as its purpose or usage.
required: false
schema:
type: string
responses:
'200':
description: 'The ID of the newly created website.
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=SitesManager.getSiteSettings:
get:
tags:
- SitesManager
description: Returns the editable measurable settings metadata for a website.
operationId: SitesManager.getSiteSettings
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: idSite
in: query
description: The numeric ID of the website to inspect.
required: true
schema:
type: integer
example: 1
responses:
'200':
description: 'Formatted measurable settings grouped by plugin, each containing setting definitions and values.
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=SitesManager.deleteSite:
get:
tags:
- SitesManager
description: Delete a website from the database, given its ID.
operationId: SitesManager.deleteSite
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: idSite
in: query
description: The numeric ID of the website to delete.
required: true
schema:
type: integer
example: 1
- name: passwordConfirmation
in: query
description: The current user's password. Only required when the request is authenticated with a session token.
required: false
schema:
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=SitesManager.addSiteAliasUrls:
get:
tags:
- SitesManager
description: Add a list of alias URLs to the given website.
operationId: SitesManager.addSiteAliasUrls
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: idSite
in: query
description: The numeric ID of the website to update.
required: true
schema:
type: integer
example: 1
- name: urls
in: query
description: URLs to add. When calling the API via HTTP specify multiple URLs via `&urls[]=http...&urls[]=http...`.
required: true
schema:
oneOf:
- type: array
items:
type: string
- type: string
example: '["https:\/\/example.org","https:\/\/example.org\/pricing"]'
responses:
'200':
description: 'The number of newly inserted URLs.
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=SitesManager.setSiteAliasUrls:
get:
tags:
- SitesManager
description: Set the list of alias URLs for the given website.
operationId: SitesManager.setSiteAliasUrls
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: idSite
in: query
description: The numeric ID of the website to update.
required: true
schema:
type: integer
example: 1
- name: urls
in: query
description: Alias URLs to persist for the website.
required: false
schema:
type: array
items:
type: string
default: []
responses:
'200':
description: 'The number of newly inserted URLs.
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=SitesManager.getIpsForRange:
get:
tags:
- SitesManager
description: Get the start and end IP addresses for an IP address range.
operationId: SitesManager.getIpsForRange
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: ipRange
in: query
description: IP address range in presentation format (e.g. `'192.168.1.0/24'`).
required: true
schema:
type: string
example: 203.0.113.0/24
responses:
'200':
description: 'Low and high IP addresses in presentation format, or `false` on error.
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=SitesManager.setGlobalExcludedIps:
get:
tags:
- SitesManager
description: Sets IPs to be excluded from all websites. IPs can contain wildcards.
operationId: SitesManager.setGlobalExcludedIps
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: excludedIps
in: query
description: Comma-separated list of IPs to exclude from being tracked (allows wildcards).
required: true
schema:
type: string
example: 203.0.113.10,203.0.113.11
responses:
'200':
description: 'Always `true`.
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=SitesManager.setGlobalSearchParameters:
get:
tags:
- SitesManager
description: Sets global Site Search keyword/category parameter names, to be used on websites which have not specified these values individually.
operationId: SitesManager.setGlobalSearchParameters
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: searchKeywordParameters
in: query
description: Comma-separated site search keyword parameter names.
required: true
schema:
type: string
example: q,query,keyword
- name: searchCategoryParameters
in: query
description: Comma-separated site search category parameter names.
required: true
schema:
type: string
example: category,cat
responses:
'200':
description: 'Always `true`.
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=SitesManager.getSearchKeywordParametersGlobal:
get:
tags:
- SitesManager
description: Returns the global site search keyword parameter names.
operationId: SitesManager.getSearchKeywordParametersGlobal
parameters:
- $ref: '#/components/parameters/formatOptional'
responses:
'200':
description: 'Comma-separated list of keyword parameter names.
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=SitesManager.getSearchCategoryParametersGlobal:
get:
tags:
- SitesManager
description: Returns the global site search category parameter names.
operationId: SitesManager.getSearchCategoryParametersGlobal
parameters:
- $ref: '#/components/parameters/formatOptional'
responses:
'200':
description: 'Comma-separated list of URL parameter names, or `false` if not configured.
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=SitesManager.getExcludedQueryParameters:
get:
tags:
- SitesManager
description: Returns the list of URL query parameters that are excluded for the given website
operationId: SitesManager.getExcludedQueryParameters
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: idSite
in: query
description: The numeric ID of the website to inspect.
required: true
schema:
type: integer
example: 1
responses:
'200':
description: 'List of excluded query parameter names for the requested website.
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=SitesManager.getExcludedQueryParametersGlobal:
get:
tags:
- SitesManager
description: Returns the list of URL query parameters that are excluded from all websites.
operationId: SitesManager.getExcludedQueryParametersGlobal
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: idSite
in: query
description: Optional site ID for site-specific filtering.
required: false
schema:
type: integer
responses:
'200':
description: 'Comma-separated list of URL parameters.
Example responses require Super User access. Use Try it out to see a live response.'
content:
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=SitesManager.getExcludedUserAgentsGlobal:
get:
tags:
- SitesManager
description: Returns the list of user agent substrings to look for when excluding visits for all websites. If a visitor's user agent string contains one of these substrings, their visits will not be included.
operationId: SitesManager.getExcludedUserAgentsGlobal
parameters:
- $ref: '#/components/parameters/formatOptional'
responses:
'200':
description: 'Comma separated list of strings.
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=SitesManager.setGlobalExcludedUserAgents:
get:
tags:
- SitesManager
description: Sets list of user agent substrings to look for when excluding visits.
operationId: SitesManager.setGlobalExcludedUserAgents
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: excludedUserAgents
in: query
description: Comma-separated list of strings. Each element is trimmed, and empty strings are removed.
required: true
schema:
type: string
example: HeadlessChrome,Googlebot
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=SitesManager.getExcludedReferrers:
get:
tags:
- SitesManager
description: Returns the list of URLs/hosts that should be ignored when detecting referrers for the given site.
operationId: SitesManager.getExcludedReferrers
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: idSite
in: query
description: The numeric ID of the website to inspect.
required: true
schema:
type: integer
example: 1
responses:
'200':
description: 'Excluded referrer URLs/hosts.
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=SitesManager.getExcludedReferrersGlobal:
get:
tags:
- SitesManager
description: Returns the global list of URLs/hosts that should be ignored when detecting referrers.
operationId: SitesManager.getExcludedReferrersGlobal
parameters:
- $ref: '#/components/parameters/formatOptional'
responses:
'200':
description: 'Comma-separated list of excluded referrer URLs/hosts.
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=SitesManager.setGlobalExcludedReferrers:
get:
tags:
- SitesManager
description: Sets list of URLs/hosts that should be ignored when detecting referrers.
operationId: SitesManager.setGlobalExcludedReferrers
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: excludedReferrers
in: query
description: Comma-separated list of URLs/hosts. Each element is trimmed, and empty strings are removed.
required: true
schema:
type: string
example: partner.example.com,internal.example.org
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=SitesManager.getKeepURLFragmentsGlobal:
get:
tags:
- SitesManager
description: Returns whether the default global behavior is to keep URL fragments when tracking.
operationId: SitesManager.getKeepURLFragmentsGlobal
parameters:
- $ref: '#/components/parameters/formatOptional'
responses:
'200':
description: '`true` if URL fragments are kept by default, `false` if they are removed.
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=SitesManager.setKeepURLFragmentsGlobal:
get:
tags:
- SitesManager
description: Sets whether the default behavior should be to keep URL fragments when tracking or not.
operationId: SitesManager.setKeepURLFragmentsGlobal
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: enabled
in: query
description: If `true`, the default behavior will be to keep URL fragments when tracking. If `false`, they will be removed.
required: true
schema:
type: boolean
example: true
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=SitesManager.getExcludedIpsGlobal:
get:
tags:
- SitesManager
description: Returns the list of IPs that are excluded from all websites
operationId: SitesManager.getExcludedIpsGlobal
parameters:
- $ref: '#/components/parameters/formatOptional'
responses:
'200':
description: 'Comma separated list of IPs
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=SitesManager.getDefaultCurrency:
get:
tags:
- SitesManager
description: Returns the default currency that will be set when creating a website through the API.
operationId: SitesManager.getDefaultCurrency
parameters:
- $ref: '#/components/parameters/formatOptional'
responses:
'200':
description: 'Currency code, e.g. `''USD''`.
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=SitesManager.setDefaultCurrency:
get:
tags:
- SitesManager
description: Sets the default currency that will be used when creating websites.
operationId: SitesManager.setDefaultCurrency
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: defaultCurrency
in: query
description: Currency code, e.g. `'USD'`.
required: true
schema:
type: string
example: NZD
responses:
'200':
description: 'Always `true`.
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=SitesManager.getDefaultTimezone:
get:
tags:
- SitesManager
description: Returns the default timezone that will be set when creating a website through the API.
operationId: SitesManager.getDefaultTimezone
parameters:
- $ref: '#/components/parameters/formatOptional'
responses:
'200':
description: 'Timezone identifier, e.g. `''UTC+7''` or `''Europe/Paris''`.
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=SitesManager.setDefaultTimezone:
get:
tags:
- SitesManager
description: Sets the default timezone that will be used when creating websites.
operationId: SitesManager.setDefaultTimezone
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: defaultTimezone
in: query
description: Timezone string, e.g. `'Europe/Paris'` or `'UTC+8'`.
required: true
schema:
type: string
example: Pacific/Auckland
responses:
'200':
description: 'Always `true`.
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=SitesManager.setGlobalQueryParamExclusion:
get:
tags:
- SitesManager
description: Sets global query parameter exclusion based on the specified exclusion type.
operationId: SitesManager.setGlobalQueryParamExclusion
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: exclusionType
in: query
description: 'The type of query parameter exclusion. One of: - `''common_session_parameters''` — strip common session parameters only. - `''matomo_recommended_pii''` — strip Matomo''s recommended PII parameters. - `''custom''` — strip a user-defined list of parameters.'
required: true
schema:
type: string
example: ip
- name: queryParamsToExclude
in: query
description: Comma-separated list of query parameters to exclude. Required when `$exclusionType` is `'custom'`, ignored otherwise.
required: false
schema:
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=SitesManager.getExclusionTypeForQueryParams:
get:
tags:
- SitesManager
description: Gets the exclusion type, if the option is not present in the store then it infers the type based on if there are custom exclusions already defined.
operationId: SitesManager.getExclusionTypeForQueryParams
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: idSite
in: query
description: Specific site ID when site-specific filtering is active, or `null` for global settings.
required: false
schema:
type: integer
responses:
'200':
description: 'Query parameter exclusion type 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=SitesManager.updateSite:
get:
tags:
- SitesManager
description: Update an existing website.
operationId: SitesManager.updateSite
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: idSite
in: query
description: Website ID defining the website to edit.
required: true
schema:
type: integer
example: 1
- name: siteName
in: query
description: Website name.
required: false
schema:
type: string
- name: urls
in: query
description: The website URLs. When calling the API via HTTP specify multiple URLs via `&urls[]=http...&urls[]=http...`.
required: false
schema:
oneOf:
- type: array
items:
type: string
- type: string
- name: ecommerce
in: query
description: Whether Ecommerce is enabled (`1`) or disabled (`0`).
required: false
schema:
oneOf:
- type: integer
- type: string
- name: siteSearch
in: query
description: Whether Site Search is enabled (`1`) or disabled (`0`).
required: false
schema:
oneOf:
- type: integer
- type: string
- name: searchKeywordParameters
in: query
description: Comma-separated list of search keyword parameter names.
required: false
schema:
type: string
- name: searchCategoryParameters
in: query
description: Comma-separated list of search category parameter names.
required: false
schema:
type: string
- name: excludedIps
in: query
description: Comma-separated list of IPs to exclude from being tracked (allows wildcards).
required: false
schema:
type: string
- name: excludedQueryParameters
in: query
description: Comma-separated list of URL query parameters to strip from tracked URLs.
required: false
schema:
type: string
- name: timezone
in: query
description: Timezone string, e.g. `'Europe/London'`.
required: false
schema:
type: string
- name: currency
in: query
description: Currency code, e.g. `'EUR'`.
required: false
schema:
type: string
- name: group
in: query
description: Group name where this website belongs. Requires Superuser access.
required: false
schema:
type: string
- name: startDate
in: query
description: Date at which statistics for this website will start, in `YYYY-MM-DD` format.
required: false
schema:
type: string
- name: excludedUserAgents
in: query
description: Comma-separated list of user agent substrings to exclude.
required: false
schema:
type: string
- name: keepURLFragments
in: query
description: If `1`, URL fragments will be kept when tracking. If `2`, they will be removed. If `0`, the default global behavior will be used.
required: false
schema:
oneOf:
- type: integer
- type: string
- name: type
in: query
description: The website type, e.g. `'website'`.
required: false
schema:
type: string
- name: settingValues
in: query
description: Measurable settings keyed by plugin name, each containing an array of `['name' => string, 'value' => mixed]` pairs.
required: false
schema:
type: string
- name: excludeUnknownUrls
in: query
description: Whether to track only URLs matching one of the website's registered URLs.
required: false
schema:
type: string
- name: excludedReferrers
in: query
description: Comma-separated list of hosts/URLs to exclude from referrer detection.
required: false
schema:
type: string
- name: description
in: query
description: Optional description providing additional context about this site, such as its purpose or usage.
required: false
schema:
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=SitesManager.getCurrencyList:
get:
tags:
- SitesManager
description: Returns the list of supported currencies.
operationId: SitesManager.getCurrencyList
parameters:
- $ref: '#/components/parameters/formatOptional'
responses:
'200':
description: 'Map of currency code to human-readable name with symbol, e.g. `[''USD'' => ''US Dollar ($)'', ...]`.
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=SitesManager.getCurrencySymbols:
get:
tags:
- SitesManager
description: Returns the list of currency symbols.
operationId: SitesManager.getCurrencySymbols
parameters:
- $ref: '#/components/parameters/formatOptional'
responses:
'200':
description: 'Map of currency code to its symbol, e.g. `[''USD'' => ''$'', ...]`.
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=SitesManager.isTimezoneSupportEnabled:
get:
tags:
- SitesManager
description: Returns whether timezone support is enabled on the server.
operationId: SitesManager.isTimezoneSupportEnabled
parameters:
- $ref: '#/components/parameters/formatOptional'
responses:
'200':
description: '`true` if timezone support is available.
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=SitesManager.getTimezonesList:
get:
tags:
- SitesManager
description: Returns the list of supported timezones, grouped by continent.
operationId: SitesManager.getTimezonesList
parameters:
- $ref: '#/components/parameters/formatOptional'
responses:
'200':
description: 'Timezones grouped by continent name. Each entry maps a timezone identifier to its human-readable label.
Example responses require Super User access. Use Try it out to see a live response.'
content:
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=SitesManager.getTimezoneName:
get:
tags:
- SitesManager
description: Returns a user-friendly label for a timezone.
operationId: SitesManager.getTimezoneName
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: timezone
in: query
description: A timezone, e.g. `'Asia/Tokyo'` or `'America/Los_Angeles'`.
required: true
schema:
type: string
example: Pacific/Auckland
- name: countryCode
in: query
description: An upper-case country code, or `null` to look it up automatically.
required: false
schema:
type: string
- name: multipleTimezonesInCountry
in: query
description: Whether there are multiple timezones in the country, or `null` to look it up automatically.
required: false
schema:
type: string
responses:
'200':
description: 'a timezone label, e.g. "Japan" or "United States - Los Angeles"
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=SitesManager.getUniqueSiteTimezones:
get:
tags:
- SitesManager
description: Returns the list of unique timezones from all configured sites.
operationId: SitesManager.getUniqueSiteTimezones
parameters:
- $ref: '#/components/parameters/formatOptional'
responses:
'200':
description: 'Distinct timezone identifiers currently in use.
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=SitesManager.renameGroup:
get:
tags:
- SitesManager
description: Renames a website group across all sites that currently use it.
operationId: SitesManager.renameGroup
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: oldGroupName
in: query
description: Existing group name to replace.
required: true
schema:
type: string
example: Marketing Team
- name: newGroupName
in: query
description: New group name to assign.
required: true
schema:
type: string
example: Growth Team
responses:
'200':
description: 'Always `true`.
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=SitesManager.getPatternMatchSites:
get:
tags:
- SitesManager
description: Find websites matching the given pattern.
operationId: SitesManager.getPatternMatchSites
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: pattern
in: query
description: Search string to match against site name, URL or group.
required: true
schema:
type: string
example: https://example.org/pricing
- name: limit
in: query
description: Maximum number of sites to return, or `false` for no limit.
required: false
schema:
oneOf:
- type: integer
- type: string
- name: sitesToExclude
in: query
description: Site IDs to exclude from the result.
required: false
schema:
type: array
items:
type: integer
default: []
responses:
'200':
description: 'Matching websites.
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=SitesManager.getNumWebsitesToDisplayPerPage:
get:
tags:
- SitesManager
description: Returns the number of websites to display per page.
operationId: SitesManager.getNumWebsitesToDisplayPerPage
parameters:
- $ref: '#/components/parameters/formatOptional'
responses:
'200':
description: 'Number of websites per page.
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: ''
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/