PmaControl — developers and API
Quick start
Query the public resources below with curl. No account, sales form or API key is needed for this read-only API. Responses use JSON.
curl -sS https://www.pmacontrol.com/api/v1/capabilities
curl -sS 'https://www.pmacontrol.com/api/v1/documentation?language=en'
curl -sS https://www.pmacontrol.com/api/v1/permissions
Authentication and permissions
Discovery resources and the public sandbox remain available without credentials. To test an authenticated integration, self-register a confidential OAuth client at /oauth/register, then request a client_credentials token at /oauth/token. The sandbox.servers.read and sandbox.identity.read scopes are declared in OpenAPI and enforced on protected routes. Client secrets expire after 24 hours and tokens after at most 600 seconds. These credentials grant no access to customer installations; their access remains separately administered.
Contract and errors
The OpenAPI contract describes every operation, parameter and response. API errors use application/problem+json. Public requests are limited to 300 per client IP in 60 seconds. RateLimit-Policy and RateLimit declare the policy, remaining quota and seconds until reset; RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset are also provided for compatibility. After HTTP 429, wait for the seconds in Retry-After. These fields follow IETF draft httpapi-ratelimit-headers-11; no availability guarantee is promised.
Free sandbox
Test a synthetic MariaDB / MySQL response without an account or key. Metrics are fixed examples with no connection to customer databases. This sandbox is read-only and does not simulate production permissions. The existing Pro trial requires email verification and an installation UUID; its license is not an API key.
curl -sS https://www.pmacontrol.com/api/v1/sandbox/servers
Official PmaControl CLI
Install the CLI from the official Homebrew tap on macOS or Linux. The formula uses Python 3.13 and verifies the published source archive with SHA-256. The capabilities, permissions, schema, docs and sandbox commands return JSON without an account or key. The package and its source are publicly accessible on this website.
brew tap pmacontrol/agent https://www.pmacontrol.com/downloads/homebrew-agent.git
brew install pmacontrol/agent/pmacontrol-agent
pmacontrol-agent --version
pmacontrol-agent capabilities
pmacontrol-agent docs --language fr
pmacontrol-agent sandbox
Self-service sandbox credentials
The flow below creates a client ID and secret without signup or payment, then a token limited to sandbox.servers.read. Replace CLIENT_ID, CLIENT_SECRET and ACCESS_TOKEN with the returned values. To test client identity, explicitly request sandbox.identity.read. Registration is limited to five clients per hour per IP and 120 per hour for the service; the token endpoint accepts 30 requests per minute per IP. Current quota headers and Retry-After take precedence.
curl -sS https://www.pmacontrol.com/oauth/register \
-H 'Content-Type: application/json' \
--data '{"grant_types":["client_credentials"],"response_types":[],"scope":"sandbox.servers.read"}'
curl -sS https://www.pmacontrol.com/oauth/token \
--user 'CLIENT_ID:CLIENT_SECRET' \
--data 'grant_type=client_credentials&scope=sandbox.servers.read'
curl -sS https://www.pmacontrol.com/api/v1/sandbox/authorized-servers \
-H 'Authorization: Bearer ACCESS_TOKEN'
Machine-readable onboarding guide
API versioning and deprecation
REST API v1 is active and the current contract version is 1.1.0. Compatible additions use a minor version; breaking changes require a new major URL, such as /api/v2. No v1 retirement is scheduled. Before retirement, we publish a dated notice and migration guide at least 90 days in advance, except for a documented security emergency or legal requirement.
When a resource is deprecated, Deprecation carries an RFC 9745 Structured Field Date as @Unix_seconds and Sunset carries the retirement HTTP-date in GMT under RFC 8594. Sunset is never earlier than Deprecation. The HTTP rel=deprecation link points to this policy and migration instructions. Active resources expose that link without announcing a fictional date.