Read and interact with Matomo API through Swagger UI with full OpenAPI 3.1.0 compliance.
This plugin brings the OpenAPI standard to your Matomo Instance, providing a complete, interactive API documentation that automatically discovers all installed plugins and their API methods.
Overview
The Swagger plugin provides a complete, interactive OpenAPI 3.1.0 compliant documentation for your Matomo API. It automatically discovers all installed plugins and their API methods, providing a user-friendly interface to explore and test the Matomo API.
How to Access the Swagger UI
The Swagger UI is available only to Super Users for security reasons.
Access Path: 1. Log in to Matomo as a Super User 2. Navigate to Administration > Platform > Swagger 3. The Swagger UI will load with all available API endpoints
Authentication
The plugin uses modern Bearer token authentication for security.
Setup Authentication: 1. Click the Authorize button (lock icon) in the top-right of Swagger UI 2. Enter your Matomo API token in the value field 3. Click Authorize to save 4. Click Close to return to the API documentation
Finding Your API Token: - Go to Administration > Platform > API - Under User Authentication, create a new token or copy an existing one - Optionally restrict the token to POST requests only for enhanced security
Token Format:
Authorization: Bearer YOUR_API_TOKEN
Using the Swagger UI
Browsing API Methods: - API methods are organized by plugin (tags on the left sidebar) - Click on any plugin name to expand its available methods - Each method shows its description, parameters, and response format
Testing an API Call: 1. Click on any API endpoint to expand it 2. Click the Try it out button 3. Fill in the required parameters (marked with red asterisk) 4. Optionally fill in optional parameters 5. Click Execute to send the request 6. View the response below, including status code, headers, and body
Understanding Parameters:
- module: Always set to "API" (pre-filled, read-only)
- format: Response format (json, xml, csv, tsv, html, rss, original) - defaults to json
- Method-specific parameters: Each API method has its own parameters documented in the UI
Response Formats:
The API supports multiple response formats:
- json - JSON format (default, recommended)
- xml - XML format
- csv - Comma-separated values
- tsv - Tab-separated values
- html - HTML table format
- rss - RSS feed format
- original - Original PHP serialized format
Dynamic API Discovery
The plugin automatically discovers all API methods from: - Core Matomo plugins: Actions, API, Dashboard, Goals, etc. - Premium plugins: AbTesting, Cohorts, Funnels, Heatmaps, etc. - Custom plugins: Any plugin with an API class
No Manual Configuration Required: - Install a new plugin → API methods appear automatically - Activate a plugin → Methods become available - Deactivate a plugin → Methods are hidden - Always in sync with your Matomo installation
Advanced Features
POST Method Support
All API calls use POST methods for enhanced security: - Compatible with POST-only API token restrictions - Prevents token exposure in server logs - Better suited for authenticated API calls - Supports both form-urlencoded and JSON request bodies
Content Type Options
Choose between two request formats: - application/x-www-form-urlencoded: Standard form data (default) - application/json: JSON request bodies
Switch between them in the "Request body" section of each endpoint.
Protocol Detection
The plugin automatically detects your server configuration: - HTTPS installations: Uses https:// for all endpoints - HTTP installations: Uses http:// for all endpoints - Reverse proxy setups: Respects X-Forwarded-Proto headers
No manual configuration needed for different environments.
Embed the Swagger UI (Optional)
You can embed the Swagger UI in your own tools or dashboards using an iframe.
Basic Embed:
<iframe src="/index.php?module=Swagger&action=iframe" width="100%" height="800px"></iframe>
Auto-Resize Iframe:
<!-- Auto resize iframe height (optional) -->
<script>
function resizeIframe(obj) {
setInterval(() => {
obj.style.height = obj.contentWindow.document.documentElement.scrollHeight + 'px';
}, 500);
}
</script>
<!-- Swagger UI (required) -->
<iframe
src="/index.php?module=Swagger&action=iframe"
width="100%"
onload="resizeIframe(this);"
frameborder="0">
</iframe>
Important Notes: - The iframe inherits authentication from the parent Matomo session - Users must be logged in as Super User to view the embedded Swagger UI - The iframe URL must be from the same Matomo instance (CORS restrictions apply)
Export OpenAPI Specification (Optional)
The OpenAPI JSON specification file is accessible via the Matomo API for external tools.
API Endpoint:
POST /index.php
Content-Type: application/x-www-form-urlencoded
module=API&format=json&method=Swagger.getOpenApi&token_auth=YOUR_TOKEN
Using cURL:
curl -X POST "https://your-matomo-domain/index.php" \
-d "module=API" \
-d "format=json" \
-d "method=Swagger.getOpenApi" \
-d "token_auth=YOUR_API_TOKEN"
Use Cases: - Import into external API testing tools (Postman, Insomnia) - Generate client SDKs using OpenAPI Generator - Create custom documentation websites - Integrate with API gateways - Automated API testing and validation
OpenAPI File Structure:
{
"openapi": "3.1.0",
"info": {
"title": "Matomo API",
"version": "5.6.0"
},
"servers": [...],
"tags": [...],
"paths": {...},
"components": {
"securitySchemes": {
"BearerAuth": {...}
}
}
}
Version Information
The OpenAPI specification automatically includes: - Matomo Version: Dynamically detected from your installation - API Version: Reflects your current Matomo version - Plugin Versions: All installed plugin information
No need to manually update version numbers - it's always accurate.
Security Considerations
Access Control: - Only Super Users can access the Swagger UI - Regular users cannot view or use the plugin - API tokens can be restricted to specific permissions
Token Security: - Use POST-only tokens when possible - Create separate tokens for Swagger UI testing - Regularly rotate API tokens - Never commit tokens to version control - Tokens are sent in Authorization header (not URL)
Best Practices: - Test API calls in development environment first - Use read-only methods when exploring the API - Be careful with DELETE and UPDATE operations - Monitor API usage in Matomo logs
Troubleshooting
Common Issues:
"You can't access this resource" error
- Ensure you're logged in as Super User
- Check that the plugin is activated
"Unable to authenticate" error
- Verify your API token is valid
- Ensure the token is for a Super User account
- Try using POST method for token submission
"No operations defined in spec" error
- Check Matomo error logs for details
- Verify all plugins are properly activated
- Look for PHP errors in the installation
API methods missing
- Ensure the plugin is activated
- Check that the plugin has an API class
- Try deactivating and reactivating the plugin
Swagger UI not loading
- Clear browser cache
- Check browser console for JavaScript errors
- Verify no plugin conflicts
- Ensure JavaScript is enabled
For more help, see the FAQ or check the Matomo forums.
Additional Resources
Installation & Setup
How do I install this plugin?
This plugin is available in the official Matomo Marketplace:
- Go to Administration > Platform > Marketplace
- Select Plugins from the dropdown
- Search for Swagger
- Click Install and then Activate
- Access it from Administration > Platform > Swagger
Where do I find my API token?
Your Matomo API token is located at: Administration > Platform > API > User Authentication
You can create a new token or use an existing one with appropriate permissions.
Can I restrict the API token to POST requests only?
Yes! The Swagger plugin fully supports POST-only API tokens. When creating or editing an API token, you can restrict it to POST requests for enhanced security. The Swagger UI will use POST methods for all API calls.
Access & Permissions
Who can access the Swagger UI?
Only Super Users have access to the Swagger plugin. This is a security measure since the Swagger UI provides access to all API methods, including administrative functions.
Can I give access to non-Super Users?
Not directly through this plugin. However, you can: - Export the OpenAPI JSON file and host it on a separate Swagger UI instance - Grant users the specific API tokens with limited permissions - Use Matomo's built-in role management for API access
Usage
What does this plugin do?
The Swagger plugin generates a complete OpenAPI 3.1.0 compliant documentation for your Matomo API based on your installed plugins. It provides: - Interactive API documentation - Ability to test API calls directly from the browser - Automatic discovery of all available API methods - Real-time parameter validation - Response previews with examples
Do I need to update the plugin when I install new Matomo plugins?
No! The Swagger plugin automatically discovers all installed and activated plugins. When you install or activate a new plugin with API methods, they will automatically appear in the Swagger UI without any manual configuration.
Why are some API methods not showing up?
API methods will only appear if: - The plugin is activated in Matomo - The plugin has an API class with public methods - The plugin API is properly registered
Try deactivating and reactivating the plugin if methods are missing.
Can I use the Swagger UI to test API calls?
Yes! The Swagger UI is fully interactive: 1. Click Authorize and enter your API token 2. Browse to any API endpoint 3. Click Try it out 4. Fill in the required parameters 5. Click Execute to see the response
Technical Questions
What OpenAPI version does this plugin support?
The plugin generates OpenAPI 3.1.0 compliant specifications, the latest version of the OpenAPI standard.
Can I export the OpenAPI specification?
Yes! The OpenAPI JSON file is available at:
POST /index.php
Body: module=API&format=json&method=Swagger.getOpenApi&token_auth=YOUR_TOKEN
Or access it through the API with your token.
Does this plugin work with HTTP and HTTPS?
Yes! The plugin automatically detects your server's protocol (HTTP or HTTPS) and configures the API endpoints accordingly. It works with: - Standard HTTPS installations - HTTP development environments - Reverse proxy configurations
What content types are supported?
The Swagger UI supports both:
- application/x-www-form-urlencoded (standard form data)
- application/json (JSON request bodies)
You can switch between them in the Swagger UI for each request.
Are there any breaking changes from previous versions?
Version 5.2.0 introduces some changes: - API calls now use POST method instead of GET (more secure) - Authentication uses Bearer token in Authorization header (modern standard) - Plugin descriptions removed from tags (cleaner UI)
All existing API endpoints remain compatible.
Development & Contribution
How can I contribute to this plugin?
Contributions are welcome! You can: - Report issues on the project repository - Submit pull requests with improvements - Suggest new features - Help improve documentation - Test the plugin with different Matomo configurations
How long will this plugin be maintained?
This plugin is actively maintained. As the developer uses Matomo across multiple projects, updates and bug fixes are prioritized to ensure compatibility with new Matomo versions.
Can I embed the Swagger UI in my own application?
Yes! See the documentation for details on embedding the Swagger UI via iframe.
Troubleshooting
I'm getting authentication errors
Make sure: - Your API token is valid and not expired - You're using a Super User token - The token is sent as POST parameter or Bearer header - You've clicked Authorize in the Swagger UI
The Swagger UI is not loading
Check that: - You have Super User access - The plugin is activated - Your browser allows JavaScript execution - There are no conflicting plugins
API calls are failing with 403 errors
This usually means: - Your API token doesn't have sufficient permissions - The token is expired or invalid - You're not authenticated in Matomo
I see "No operations defined in spec" error
This indicates an error generating the OpenAPI specification. Check: - Matomo error logs for details - That all plugins are properly activated - That there are no PHP errors in the Matomo installation
-
A Swagger logo
-
Swagger
-
Swagger Goals API
