Explore and try every Matomo API method from your admin panel, with Swagger UI and an OpenAPI 3.1 specification generated live from your activated plugins.
Features
- Interactive API explorer under Administration > Platform > Swagger, powered by Swagger UI and displayed in a same-origin frame.
- Always in sync: the OpenAPI 3.1 document is generated on demand from the plugins activated on your Matomo, so installing or removing a plugin updates it immediately. No static file to maintain.
- Bearer token authentication: click Authorize and paste a Matomo API token, it is sent as an
Authorization: Bearer header, never as a token_auth query parameter.
- Accurate documentation: modules described with each plugin's own description and homepage link, parameters typed from the PHP signatures (
int, bool, float, array) with required flags and defaults, and request examples from Matomo's own API documentation generator.
- Matomo-aware parameters:
period, idSite / idSites (1, 1,2,3 or all), date keywords and ranges, segment and language are documented.
- Works with POST-only tokens: every method is described as a POST request, and every response format Matomo can return is documented (
json, xml, csv, tsv, html, rss, original).
- Importable OpenAPI document, served by the
Swagger.getOpenApi API method (?module=API&format=json&method=Swagger.getOpenApi) with a Super User token, for Postman, Insomnia or an SDK generator.
- Works from a subdirectory: the server URL and the Swagger UI assets keep the path Matomo is installed in.
The session-based "Try it out", the search field, the one-click download, the widget, dark mode and the translations are only available in Swagger 6.x, for Matomo 6.
Requirements
- Matomo 5.0.0 or higher (
>=5.0.0,<6.0.0-b1)
- A Super User account
- A Matomo API token with the permissions matching the calls you want to make
Installation / Configuration
- Install the plugin from the Matomo Marketplace (Administration > Marketplace), or copy it to
plugins/Swagger and activate it under Administration > System > Plugins. The plugin creates no database table and leaves no data behind when deactivated.
- Open Administration > Platform > Swagger.
- Click Authorize and paste a token created under Administration > Personal > Security.
- Expand an API module, open a method, click Try it out, fill in the parameters and click Execute.
There is no setting. The plugin only relaxes the Content Security Policy of its own two pages (frame-src 'self' for the frame, img-src validator.swagger.io for the Swagger UI validator badge).
Privacy and data
- The Swagger page and the
Swagger.getOpenApi method require Super User access.
- The plugin never stores tokens: a token entered with Authorize only lives in the browser tab.
- The OpenAPI document describes the API methods only. It contains no credentials, configuration values or website data.
- "Try it out" requests go to your own Matomo server. The document also lists the public demo.matomo.cloud server as an alternative target, and the Swagger UI validator badge is loaded from validator.swagger.io.
Need help with Matomo?
Openmost is an official Matomo Implementation Partner. When you are ready to connect Matomo to your CMS, CRM, BI tools or data warehouse, we build Matomo integrations on the official APIs, with documented data flows your team can take over.
-
API explorer generated from your plugins
-
Authorize with a Bearer API token
-
Typed parameters with Matomo documentation
1 - Install the plugin
Install this plugin from the Marketplace as a Super User, or download it and copy it to the /plugins folder of your Matomo.
Then activate the plugin under Administration > System > Plugins.
2 - Open the API explorer
As a Super User, go to Administration > Platform > Swagger.
The page lists every Reporting API module of your Matomo, each with the description of its plugin. Expand a module to see its methods. The specification is generated from the activated plugins each time the page is opened: when you activate or deactivate a plugin, its methods appear or disappear automatically.
3 - Authorize an API token
- Click Authorize.
- Paste an API token. Tokens are created under Administration > Personal > Security, and can be restricted to POST requests.
- Click Authorize, then Close.
The token is sent in the Authorization: Bearer header and is never stored by the plugin.
4 - Try an API method
- Expand a method, for example
VisitsSummary.get.
- Click Try it out.
- Fill in the required parameters, marked with a red asterisk. Examples are suggested for
idSite, period and date.
- Keep the
application/x-www-form-urlencoded request body: the Matomo API reads its parameters from form fields, not from a JSON body.
- Click Execute to send the request and read the response.
5 - Export the OpenAPI specification
The specification is returned by the Swagger.getOpenApi API method, which requires a Super User token. Import it in Postman, Insomnia, an API gateway or an SDK generator such as OpenAPI Generator:
curl -X POST "https://matomo.example.com/index.php" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d "module=API" \
-d "method=Swagger.getOpenApi" \
-d "format=json"
How the specification is built
- Every API method is described as a POST request on
index.php, with the method name in the path.
- Parameter types come from the PHP signature of each method. Parameters without a default value are required. Internal parameters (starting with
_) are hidden.
period, idSite / idSites, date, segment and language get Matomo-specific schemas and descriptions.- Request examples come from Matomo's own API documentation generator.
- The server URL is the URL you use to open Matomo, so the explorer also works when Matomo is installed in a subfolder.
- The response documents every format Matomo can return:
json, xml, csv, tsv, html, rss and original.
Troubleshooting
The page shows "You can't access this resource"
The Swagger page requires Super User access.
The page stays blank
Another plugin or a custom Content Security Policy may override frame-src. The plugin only allows frame-src 'self' on its own page, to display Swagger UI in a same-origin frame.
A plugin's methods are missing
Check that the plugin is activated. Only the API methods of activated plugins are listed.
A request returns "token_auth is not valid"
The token entered with Authorize is invalid, revoked, or lacks access to the requested site.
A request is slow or times out
Heavy reports can take time to process. Try a shorter period and date first, or lower filter_limit.
Which Matomo versions are supported?
Version 5.x of the plugin supports Matomo 5.0.0 or higher. For Matomo 6, install version 6.x of the plugin, which also lets you try the API with your Matomo session, without a token.
Who can use the API explorer?
Only Super Users. The explorer gives access to every API method, including administration methods, so it is restricted like the other platform tools.
Do I need an API token to try the API?
Yes. Click Authorize and paste a token created under Administration > Personal > Security.
Can I use a token restricted to POST requests?
Yes. Every method is called with a POST request and the token is sent in the Authorization: Bearer header.
Do I need to update anything when I install a new plugin?
No. The specification is generated from the activated plugins each time the explorer is opened.
Which OpenAPI version is generated?
OpenAPI 3.1.0.
Can I import the specification in Postman or generate an SDK?
Yes. Request the Swagger.getOpenApi API method with a Super User token. See the documentation for an example.
Why should I not send a JSON request body?
The Matomo API reads its parameters from the query string and form fields only. Keep the application/x-www-form-urlencoded request body in Swagger UI.
Does the plugin work when Matomo is installed in a subfolder?
Yes. The server URL and the Swagger UI assets keep the path Matomo is installed in.
Does the plugin slow down Matomo?
No. Swagger UI is only loaded on the explorer page, and the specification is only generated when the explorer is opened.
Does the plugin store data?
No. It creates no database table and never stores tokens.
