{
  "openapi": "3.1.1",
  "info": {
    "title": "PmaControl Public Discovery API",
    "version": "1.1.0",
    "description": "Read-only product and documentation discovery for PmaControl, the MariaDB / MySQL operations platform. This public website API never returns customer infrastructure data. Production installation APIs have separate authentication and URLs. REST v1 is active. Compatible additions use minor versions; breaking changes use a new major URL. Deprecation policy and minimum notice are published in externalDocs and /api-policy.json.",
    "contact": {
      "name": "PmaControl",
      "email": "contact@pmacontrol.com",
      "url": "https://www.pmacontrol.com/contact"
    }
  },
  "servers": [
    {
      "url": "https://www.pmacontrol.com",
      "description": "Public discovery; no customer database access"
    }
  ],
  "security": [],
  "tags": [
    {
      "name": "Discovery",
      "description": "Public read-only product resources"
    },
    {
      "name": "Sandbox",
      "description": "Read-only fixed synthetic data with optional scoped authentication."
    },
    {
      "name": "Sandbox OAuth",
      "description": "Self-service expiring confidential sandbox clients and client_credentials tokens."
    }
  ],
  "paths": {
    "/api/v1/capabilities": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "operationId": "getPmaControlCapabilities",
        "summary": "Discover the public API",
        "description": "Return public product identity and links to the authoritative API contract and product documentation. No account or API key is required. This endpoint does not report production infrastructure health.",
        "security": [],
        "responses": {
          "200": {
            "description": "Public discovery metadata",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "product",
                    "api_version",
                    "access",
                    "documentation_url",
                    "openapi_url"
                  ],
                  "properties": {
                    "product": {
                      "type": "string",
                      "const": "PmaControl"
                    },
                    "api_version": {
                      "type": "string",
                      "const": "1.1.0"
                    },
                    "access": {
                      "type": "string",
                      "const": "public-read-only"
                    },
                    "documentation_url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "openapi_url": {
                      "type": "string",
                      "format": "uri"
                    }
                  },
                  "description": "Identity of this public discovery API; does not report production health."
                },
                "examples": {
                  "illustrative": {
                    "summary": "Illustrative typed response. Credential values are nonfunctional examples.",
                    "value": {
                      "product": "PmaControl",
                      "api_version": "1.1.0",
                      "access": "public-read-only",
                      "documentation_url": "https://www.pmacontrol.com/en/site/documentation/",
                      "openapi_url": "https://www.pmacontrol.com/openapi.json"
                    }
                  }
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 policy: public-api; 300 requests per 60-second fixed window per client IP.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Structured field reporting policy, remaining requests (r) and reset delay in seconds (t).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Compatibility quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "description": "Compatibility remaining quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Reset": {
                "description": "Compatibility reset delay, in seconds; not a Unix timestamp.",
                "schema": {
                  "type": "string"
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameter",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 policy: public-api; 300 requests per 60-second fixed window per client IP.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Structured field reporting policy, remaining requests (r) and reset delay in seconds (t).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Compatibility quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "description": "Compatibility remaining quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Reset": {
                "description": "Compatibility reset delay, in seconds; not a Unix timestamp.",
                "schema": {
                  "type": "string"
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 policy: public-api; 300 requests per 60-second fixed window per client IP.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Structured field reporting policy, remaining requests (r) and reset delay in seconds (t).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Compatibility quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "description": "Compatibility remaining quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Reset": {
                "description": "Compatibility reset delay, in seconds; not a Unix timestamp.",
                "schema": {
                  "type": "string"
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 policy: public-api; 300 requests per 60-second fixed window per client IP.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Structured field reporting policy, remaining requests (r) and reset delay in seconds (t).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Compatibility quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "description": "Compatibility remaining quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Reset": {
                "description": "Compatibility reset delay, in seconds; not a Unix timestamp.",
                "schema": {
                  "type": "string"
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "429": {
            "description": "Client quota exhausted; wait for Retry-After seconds.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before making another request.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "x-required-permissions": [
          "discovery.read"
        ]
      }
    },
    "/api/v1/permissions": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "operationId": "getPmaControlPermissions",
        "summary": "Read permission and authentication boundaries",
        "description": "Return verified, deployment-dependent installation permission names and the anonymous public API boundary. These permissions are not OAuth scopes; no OAuth authorization server is advertised.",
        "security": [],
        "x-required-permissions": [
          "discovery.read"
        ],
        "responses": {
          "200": {
            "description": "Permission catalog and authentication boundaries",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "public_api",
                    "installation_api",
                    "oauth"
                  ],
                  "properties": {
                    "public_api": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "authentication",
                        "permissions",
                        "customer_data",
                        "credential_required"
                      ],
                      "properties": {
                        "authentication": {
                          "type": "string"
                        },
                        "permissions": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "customer_data": {
                          "type": "boolean"
                        },
                        "credential_required": {
                          "type": "boolean"
                        }
                      }
                    },
                    "installation_api": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "authentication",
                        "availability",
                        "source_revision",
                        "permissions"
                      ],
                      "properties": {
                        "authentication": {
                          "type": "string"
                        },
                        "availability": {
                          "type": "string"
                        },
                        "source_revision": {
                          "type": "string"
                        },
                        "permissions": {
                          "type": "object",
                          "additionalProperties": false,
                          "required": [
                            "backup.read",
                            "backup.plan",
                            "backup.operate",
                            "clickhouse.route.operate"
                          ],
                          "properties": {
                            "backup.read": {
                              "type": "string"
                            },
                            "backup.plan": {
                              "type": "string"
                            },
                            "backup.operate": {
                              "type": "string"
                            },
                            "clickhouse.route.operate": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    },
                    "oauth": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "available",
                        "reason",
                        "issuer",
                        "token_endpoint",
                        "registration_endpoint",
                        "scopes_supported"
                      ],
                      "properties": {
                        "available": {
                          "type": "boolean"
                        },
                        "reason": {
                          "type": "string"
                        },
                        "issuer": {
                          "type": "string",
                          "format": "uri"
                        },
                        "token_endpoint": {
                          "type": "string",
                          "format": "uri"
                        },
                        "registration_endpoint": {
                          "type": "string",
                          "format": "uri"
                        },
                        "scopes_supported": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  },
                  "description": "Public and deployment-dependent installation permissions, plus real synthetic sandbox OAuth scope declarations. Sandbox credentials never grant installation permissions."
                },
                "examples": {
                  "illustrative": {
                    "summary": "Illustrative typed response. Credential values are nonfunctional examples.",
                    "value": {
                      "public_api": {
                        "authentication": "none",
                        "permissions": [
                          "discovery.read"
                        ],
                        "customer_data": false,
                        "credential_required": false
                      },
                      "installation_api": {
                        "authentication": "http-basic-over-tls",
                        "availability": "deployment-dependent; not hosted on the public website",
                        "source_revision": "c3e2eefb7c226a1db7f185fd33be52b3f6e08dd4",
                        "permissions": {
                          "backup.read": "Read backup state for the credential tenant.",
                          "backup.plan": "Preflight and create backup plans for the credential tenant.",
                          "backup.operate": "Run, cancel, verify and transfer tenant backups; signed mutations required.",
                          "clickhouse.route.operate": "Operate ClickHouse routes within the credential client scope."
                        }
                      },
                      "oauth": {
                        "available": true,
                        "reason": "OAuth client_credentials is available for the synthetic sandbox only. It grants no customer or production installation permissions.",
                        "issuer": "https://www.pmacontrol.com",
                        "token_endpoint": "https://www.pmacontrol.com/oauth/token",
                        "registration_endpoint": "https://www.pmacontrol.com/oauth/register",
                        "scopes_supported": [
                          "sandbox.servers.read",
                          "sandbox.identity.read"
                        ]
                      }
                    }
                  }
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 policy: public-api; 300 requests per 60-second fixed window per client IP.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Structured field reporting policy, remaining requests (r) and reset delay in seconds (t).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Compatibility quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "description": "Compatibility remaining quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Reset": {
                "description": "Compatibility reset delay, in seconds; not a Unix timestamp.",
                "schema": {
                  "type": "string"
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameter",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 policy: public-api; 300 requests per 60-second fixed window per client IP.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Structured field reporting policy, remaining requests (r) and reset delay in seconds (t).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Compatibility quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "description": "Compatibility remaining quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Reset": {
                "description": "Compatibility reset delay, in seconds; not a Unix timestamp.",
                "schema": {
                  "type": "string"
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 policy: public-api; 300 requests per 60-second fixed window per client IP.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Structured field reporting policy, remaining requests (r) and reset delay in seconds (t).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Compatibility quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "description": "Compatibility remaining quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Reset": {
                "description": "Compatibility reset delay, in seconds; not a Unix timestamp.",
                "schema": {
                  "type": "string"
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 policy: public-api; 300 requests per 60-second fixed window per client IP.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Structured field reporting policy, remaining requests (r) and reset delay in seconds (t).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Compatibility quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "description": "Compatibility remaining quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Reset": {
                "description": "Compatibility reset delay, in seconds; not a Unix timestamp.",
                "schema": {
                  "type": "string"
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "429": {
            "description": "Client quota exhausted; wait for Retry-After seconds.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before making another request.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/documentation": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "operationId": "listPmaControlDocumentation",
        "summary": "List public PmaControl technical guides",
        "description": "Return the bounded public technical guide index with localized URLs. Titles use the French source labels. No customer infrastructure or installation credentials are exposed. At most 64 guides are returned; pagination is not needed for this fixed catalog.",
        "security": [],
        "x-required-permissions": [
          "discovery.read"
        ],
        "parameters": [
          {
            "name": "language",
            "in": "query",
            "required": false,
            "description": "Language of the linked product documentation.",
            "schema": {
              "type": "string",
              "enum": [
                "fr",
                "en",
                "pl",
                "ru",
                "zh",
                "ar"
              ],
              "default": "en"
            }
          }
        ],
        "responses": {
          "400": {
            "description": "Invalid query parameter",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 policy: public-api; 300 requests per 60-second fixed window per client IP.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Structured field reporting policy, remaining requests (r) and reset delay in seconds (t).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Compatibility quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "description": "Compatibility remaining quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Reset": {
                "description": "Compatibility reset delay, in seconds; not a Unix timestamp.",
                "schema": {
                  "type": "string"
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 policy: public-api; 300 requests per 60-second fixed window per client IP.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Structured field reporting policy, remaining requests (r) and reset delay in seconds (t).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Compatibility quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "description": "Compatibility remaining quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Reset": {
                "description": "Compatibility reset delay, in seconds; not a Unix timestamp.",
                "schema": {
                  "type": "string"
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 policy: public-api; 300 requests per 60-second fixed window per client IP.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Structured field reporting policy, remaining requests (r) and reset delay in seconds (t).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Compatibility quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "description": "Compatibility remaining quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Reset": {
                "description": "Compatibility reset delay, in seconds; not a Unix timestamp.",
                "schema": {
                  "type": "string"
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "200": {
            "description": "Public documentation index",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "language",
                    "items"
                  ],
                  "properties": {
                    "language": {
                      "type": "string",
                      "enum": [
                        "fr",
                        "en",
                        "pl",
                        "ru",
                        "zh",
                        "ar"
                      ]
                    },
                    "items": {
                      "type": "array",
                      "maxItems": 64,
                      "items": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                          "id",
                          "title",
                          "url"
                        ],
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string",
                            "format": "uri"
                          }
                        }
                      }
                    }
                  },
                  "description": "A bounded catalog of public guide URLs."
                },
                "examples": {
                  "illustrative": {
                    "summary": "Illustrative typed response. Credential values are nonfunctional examples.",
                    "value": {
                      "language": "en",
                      "items": [
                        {
                          "id": "installation",
                          "title": "Installation & déploiement",
                          "url": "https://www.pmacontrol.com/en/site/doc/installation/"
                        },
                        {
                          "id": "serveurs",
                          "title": "Ajout de serveurs",
                          "url": "https://www.pmacontrol.com/en/site/doc/serveurs/"
                        },
                        {
                          "id": "scan",
                          "title": "Scan réseau & autodiscovery",
                          "url": "https://www.pmacontrol.com/en/site/doc/scan/"
                        },
                        {
                          "id": "monitoring",
                          "title": "Monitoring temps réel",
                          "url": "https://www.pmacontrol.com/en/site/doc/monitoring/"
                        },
                        {
                          "id": "dot3",
                          "title": "Topologie Dot3",
                          "url": "https://www.pmacontrol.com/en/site/doc/dot3/"
                        },
                        {
                          "id": "alertes",
                          "title": "Alertes & notifications",
                          "url": "https://www.pmacontrol.com/en/site/doc/alertes/"
                        },
                        {
                          "id": "digest",
                          "title": "Analyse de requêtes (Digest)",
                          "url": "https://www.pmacontrol.com/en/site/doc/digest/"
                        },
                        {
                          "id": "replication",
                          "title": "Réplication Master/Slave",
                          "url": "https://www.pmacontrol.com/en/site/doc/replication/"
                        },
                        {
                          "id": "galera",
                          "title": "Galera Cluster",
                          "url": "https://www.pmacontrol.com/en/site/doc/galera/"
                        },
                        {
                          "id": "innodb-cluster",
                          "title": "InnoDB Cluster & Group Replication",
                          "url": "https://www.pmacontrol.com/en/site/doc/innodb-cluster/"
                        },
                        {
                          "id": "vip",
                          "title": "Serveurs VIP",
                          "url": "https://www.pmacontrol.com/en/site/doc/vip/"
                        },
                        {
                          "id": "proxysql",
                          "title": "ProxySQL",
                          "url": "https://www.pmacontrol.com/en/site/doc/proxysql/"
                        },
                        {
                          "id": "maxscale",
                          "title": "MaxScale",
                          "url": "https://www.pmacontrol.com/en/site/doc/maxscale/"
                        },
                        {
                          "id": "backup",
                          "title": "Sauvegarde & restauration",
                          "url": "https://www.pmacontrol.com/en/site/doc/backup/"
                        },
                        {
                          "id": "schema-export",
                          "title": "Export de schéma versionné",
                          "url": "https://www.pmacontrol.com/en/site/doc/schema-export/"
                        },
                        {
                          "id": "cleaner",
                          "title": "Cleaner (purge de données)",
                          "url": "https://www.pmacontrol.com/en/site/doc/cleaner/"
                        },
                        {
                          "id": "binlog",
                          "title": "Binary logs",
                          "url": "https://www.pmacontrol.com/en/site/doc/binlog/"
                        },
                        {
                          "id": "api",
                          "title": "API REST",
                          "url": "https://www.pmacontrol.com/en/site/doc/api/"
                        },
                        {
                          "id": "integrations",
                          "title": "Intégrations natives",
                          "url": "https://www.pmacontrol.com/en/site/doc/integrations/"
                        },
                        {
                          "id": "percona",
                          "title": "Percona Toolkit",
                          "url": "https://www.pmacontrol.com/en/site/doc/percona/"
                        },
                        {
                          "id": "mysql-users",
                          "title": "Gestion des utilisateurs MariaDB / MySQL",
                          "url": "https://www.pmacontrol.com/en/site/doc/mysql-users/"
                        },
                        {
                          "id": "acl",
                          "title": "Contrôle d\\",
                          "url": "https://www.pmacontrol.com/en/site/doc/acl/"
                        },
                        {
                          "id": "csrf",
                          "title": "Protection CSRF (Origin + jeton scopé)",
                          "url": "https://www.pmacontrol.com/en/site/doc/csrf/"
                        },
                        {
                          "id": "agents-ia",
                          "title": "Agents IA & LLM",
                          "url": "https://www.pmacontrol.com/en/site/doc/agents-ia/"
                        },
                        {
                          "id": "glial",
                          "title": "Moteur Glial & Aspirateur",
                          "url": "https://www.pmacontrol.com/en/site/doc/glial/"
                        },
                        {
                          "id": "listener",
                          "title": "Listener (post-traitements)",
                          "url": "https://www.pmacontrol.com/en/site/doc/listener/"
                        },
                        {
                          "id": "plugins",
                          "title": "Plugins & extensions",
                          "url": "https://www.pmacontrol.com/en/site/doc/plugins/"
                        },
                        {
                          "id": "schema-interne",
                          "title": "Schéma interne (162 tables)",
                          "url": "https://www.pmacontrol.com/en/site/doc/schema-interne/"
                        }
                      ]
                    }
                  }
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 policy: public-api; 300 requests per 60-second fixed window per client IP.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Structured field reporting policy, remaining requests (r) and reset delay in seconds (t).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Compatibility quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "description": "Compatibility remaining quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Reset": {
                "description": "Compatibility reset delay, in seconds; not a Unix timestamp.",
                "schema": {
                  "type": "string"
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "429": {
            "description": "Client quota exhausted; wait for Retry-After seconds.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before making another request.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/sandbox/servers": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "operationId": "listPmaControlSandboxServers",
        "summary": "Read synthetic database server examples",
        "description": "Return a fixed, synthetic, read-only MariaDB / MySQL server fixture for free integration testing. No account or key is required. Metrics are illustrative constants and never come from customer infrastructure. This sandbox cannot test production authentication or mutations.",
        "security": [],
        "responses": {
          "200": {
            "description": "Synthetic sandbox dataset",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "environment",
                    "synthetic",
                    "read_only",
                    "servers"
                  ],
                  "properties": {
                    "environment": {
                      "type": "string",
                      "const": "sandbox"
                    },
                    "synthetic": {
                      "type": "boolean",
                      "const": true
                    },
                    "read_only": {
                      "type": "boolean",
                      "const": true
                    },
                    "servers": {
                      "type": "array",
                      "minItems": 2,
                      "maxItems": 2,
                      "items": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                          "id",
                          "engine",
                          "role",
                          "replication_lag_seconds",
                          "queries_per_second"
                        ],
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "engine": {
                            "type": "string",
                            "enum": [
                              "MariaDB",
                              "MySQL"
                            ]
                          },
                          "role": {
                            "type": "string",
                            "enum": [
                              "primary",
                              "replica"
                            ]
                          },
                          "replication_lag_seconds": {
                            "type": "integer",
                            "minimum": 0,
                            "description": "Illustrative lag in seconds."
                          },
                          "queries_per_second": {
                            "type": "number",
                            "minimum": 0,
                            "description": "Illustrative queries per second."
                          }
                        }
                      }
                    }
                  },
                  "description": "Static synthetic server metrics for read-only integration tests."
                },
                "example": {
                  "environment": "sandbox",
                  "synthetic": true,
                  "read_only": true,
                  "servers": [
                    {
                      "id": "demo-mariadb",
                      "engine": "MariaDB",
                      "role": "primary",
                      "replication_lag_seconds": 0,
                      "queries_per_second": 125.5
                    },
                    {
                      "id": "demo-mysql",
                      "engine": "MySQL",
                      "role": "replica",
                      "replication_lag_seconds": 2,
                      "queries_per_second": 64.0
                    }
                  ]
                },
                "examples": {
                  "illustrative": {
                    "summary": "Illustrative typed response. Credential values are nonfunctional examples.",
                    "value": {
                      "environment": "sandbox",
                      "synthetic": true,
                      "read_only": true,
                      "servers": [
                        {
                          "id": "demo-mariadb",
                          "engine": "MariaDB",
                          "role": "primary",
                          "replication_lag_seconds": 0,
                          "queries_per_second": 125.5
                        },
                        {
                          "id": "demo-mysql",
                          "engine": "MySQL",
                          "role": "replica",
                          "replication_lag_seconds": 2,
                          "queries_per_second": 64.0
                        }
                      ]
                    }
                  }
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 policy: public-api; 300 requests per 60-second fixed window per client IP.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Structured field reporting policy, remaining requests (r) and reset delay in seconds (t).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Compatibility quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "description": "Compatibility remaining quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Reset": {
                "description": "Compatibility reset delay, in seconds; not a Unix timestamp.",
                "schema": {
                  "type": "string"
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameter",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 policy: public-api; 300 requests per 60-second fixed window per client IP.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Structured field reporting policy, remaining requests (r) and reset delay in seconds (t).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Compatibility quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "description": "Compatibility remaining quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Reset": {
                "description": "Compatibility reset delay, in seconds; not a Unix timestamp.",
                "schema": {
                  "type": "string"
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 policy: public-api; 300 requests per 60-second fixed window per client IP.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Structured field reporting policy, remaining requests (r) and reset delay in seconds (t).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Compatibility quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "description": "Compatibility remaining quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Reset": {
                "description": "Compatibility reset delay, in seconds; not a Unix timestamp.",
                "schema": {
                  "type": "string"
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 policy: public-api; 300 requests per 60-second fixed window per client IP.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Structured field reporting policy, remaining requests (r) and reset delay in seconds (t).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Compatibility quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "description": "Compatibility remaining quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Reset": {
                "description": "Compatibility reset delay, in seconds; not a Unix timestamp.",
                "schema": {
                  "type": "string"
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "429": {
            "description": "Client quota exhausted; wait for Retry-After seconds.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before making another request.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "x-required-permissions": [
          "discovery.read"
        ]
      }
    },
    "/api/v1/sandbox/authorized-servers": {
      "get": {
        "tags": [
          "Sandbox"
        ],
        "operationId": "listPmaControlAuthorizedSandboxServers",
        "summary": "Read synthetic metrics with a scoped sandbox token",
        "description": "Read fixed synthetic MariaDB / MySQL metrics using a Bearer token with sandbox.servers.read. This authenticated sandbox has no customer data or installation access. Anonymous clients can still use /api/v1/sandbox/servers.",
        "security": [
          {
            "PmaControlSandboxOAuth": [
              "sandbox.servers.read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Synthetic sandbox dataset",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "environment",
                    "synthetic",
                    "read_only",
                    "servers"
                  ],
                  "properties": {
                    "environment": {
                      "type": "string",
                      "const": "sandbox"
                    },
                    "synthetic": {
                      "type": "boolean",
                      "const": true
                    },
                    "read_only": {
                      "type": "boolean",
                      "const": true
                    },
                    "servers": {
                      "type": "array",
                      "minItems": 2,
                      "maxItems": 2,
                      "items": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                          "id",
                          "engine",
                          "role",
                          "replication_lag_seconds",
                          "queries_per_second"
                        ],
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "engine": {
                            "type": "string",
                            "enum": [
                              "MariaDB",
                              "MySQL"
                            ]
                          },
                          "role": {
                            "type": "string",
                            "enum": [
                              "primary",
                              "replica"
                            ]
                          },
                          "replication_lag_seconds": {
                            "type": "integer",
                            "minimum": 0,
                            "description": "Illustrative lag in seconds."
                          },
                          "queries_per_second": {
                            "type": "number",
                            "minimum": 0,
                            "description": "Illustrative queries per second."
                          }
                        }
                      }
                    }
                  },
                  "description": "Static synthetic server metrics for read-only integration tests."
                },
                "example": {
                  "environment": "sandbox",
                  "synthetic": true,
                  "read_only": true,
                  "servers": [
                    {
                      "id": "demo-mariadb",
                      "engine": "MariaDB",
                      "role": "primary",
                      "replication_lag_seconds": 0,
                      "queries_per_second": 125.5
                    },
                    {
                      "id": "demo-mysql",
                      "engine": "MySQL",
                      "role": "replica",
                      "replication_lag_seconds": 2,
                      "queries_per_second": 64.0
                    }
                  ]
                },
                "examples": {
                  "illustrative": {
                    "summary": "Illustrative typed response. Credential values are nonfunctional examples.",
                    "value": {
                      "environment": "sandbox",
                      "synthetic": true,
                      "read_only": true,
                      "servers": [
                        {
                          "id": "demo-mariadb",
                          "engine": "MariaDB",
                          "role": "primary",
                          "replication_lag_seconds": 0,
                          "queries_per_second": 125.5
                        },
                        {
                          "id": "demo-mysql",
                          "engine": "MySQL",
                          "role": "replica",
                          "replication_lag_seconds": 2,
                          "queries_per_second": 64.0
                        }
                      ]
                    }
                  }
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 policy: public-api; 300 requests per 60-second fixed window per client IP.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Structured field reporting policy, remaining requests (r) and reset delay in seconds (t).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Compatibility quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "description": "Compatibility remaining quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Reset": {
                "description": "Compatibility reset delay, in seconds; not a Unix timestamp.",
                "schema": {
                  "type": "string"
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameter",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 policy: public-api; 300 requests per 60-second fixed window per client IP.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Structured field reporting policy, remaining requests (r) and reset delay in seconds (t).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Compatibility quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "description": "Compatibility remaining quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Reset": {
                "description": "Compatibility reset delay, in seconds; not a Unix timestamp.",
                "schema": {
                  "type": "string"
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 policy: public-api; 300 requests per 60-second fixed window per client IP.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Structured field reporting policy, remaining requests (r) and reset delay in seconds (t).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Compatibility quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "description": "Compatibility remaining quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Reset": {
                "description": "Compatibility reset delay, in seconds; not a Unix timestamp.",
                "schema": {
                  "type": "string"
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 policy: public-api; 300 requests per 60-second fixed window per client IP.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Structured field reporting policy, remaining requests (r) and reset delay in seconds (t).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Compatibility quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "description": "Compatibility remaining quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Reset": {
                "description": "Compatibility reset delay, in seconds; not a Unix timestamp.",
                "schema": {
                  "type": "string"
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "429": {
            "description": "Client quota exhausted; wait for Retry-After seconds.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before making another request.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or expired sandbox token.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "WWW-Authenticate": {
                "description": "RFC6750 Bearer challenge with RFC9728 resource_metadata and, where applicable, error and scope.",
                "schema": {
                  "type": "string"
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "Valid token lacks the scope required for this operation.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "WWW-Authenticate": {
                "description": "RFC6750 Bearer challenge with RFC9728 resource_metadata and, where applicable, error and scope.",
                "schema": {
                  "type": "string"
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "503": {
            "description": "Private authorization or quota storage unavailable; retry later.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "x-required-permissions": [
          "discovery.read"
        ]
      }
    },
    "/api/v1/sandbox/identity": {
      "get": {
        "tags": [
          "Sandbox"
        ],
        "operationId": "getPmaControlSandboxIdentity",
        "summary": "Read the authenticated sandbox client identity",
        "description": "Read the sandbox client identifier, granted scopes and expiry using a Bearer token with sandbox.identity.read. The response is not a user profile and does not identify a customer installation.",
        "security": [
          {
            "PmaControlSandboxOAuth": [
              "sandbox.identity.read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Authenticated synthetic sandbox client metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "environment",
                    "synthetic",
                    "read_only",
                    "client_id",
                    "scopes",
                    "expires_at"
                  ],
                  "properties": {
                    "environment": {
                      "type": "string",
                      "const": "sandbox"
                    },
                    "synthetic": {
                      "type": "boolean",
                      "const": true
                    },
                    "read_only": {
                      "type": "boolean",
                      "const": true
                    },
                    "client_id": {
                      "type": "string"
                    },
                    "scopes": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "expires_at": {
                      "type": "integer"
                    }
                  }
                },
                "examples": {
                  "illustrative": {
                    "summary": "Illustrative typed response. Credential values are nonfunctional examples.",
                    "value": {
                      "environment": "sandbox",
                      "synthetic": true,
                      "read_only": true,
                      "client_id": "ILLUSTRATIVE_SANDBOX_CLIENT_ID",
                      "scopes": [
                        "sandbox.identity.read"
                      ],
                      "expires_at": 1792887000
                    }
                  }
                }
              }
            },
            "headers": {
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameter",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 policy: public-api; 300 requests per 60-second fixed window per client IP.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Structured field reporting policy, remaining requests (r) and reset delay in seconds (t).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Compatibility quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "description": "Compatibility remaining quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Reset": {
                "description": "Compatibility reset delay, in seconds; not a Unix timestamp.",
                "schema": {
                  "type": "string"
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 policy: public-api; 300 requests per 60-second fixed window per client IP.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Structured field reporting policy, remaining requests (r) and reset delay in seconds (t).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Compatibility quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "description": "Compatibility remaining quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Reset": {
                "description": "Compatibility reset delay, in seconds; not a Unix timestamp.",
                "schema": {
                  "type": "string"
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 policy: public-api; 300 requests per 60-second fixed window per client IP.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Structured field reporting policy, remaining requests (r) and reset delay in seconds (t).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Compatibility quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "description": "Compatibility remaining quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Reset": {
                "description": "Compatibility reset delay, in seconds; not a Unix timestamp.",
                "schema": {
                  "type": "string"
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "429": {
            "description": "Client quota exhausted; wait for Retry-After seconds.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before making another request.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or expired sandbox token.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "WWW-Authenticate": {
                "description": "RFC6750 Bearer challenge with RFC9728 resource_metadata and, where applicable, error and scope.",
                "schema": {
                  "type": "string"
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "Valid token lacks the scope required for this operation.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "WWW-Authenticate": {
                "description": "RFC6750 Bearer challenge with RFC9728 resource_metadata and, where applicable, error and scope.",
                "schema": {
                  "type": "string"
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "503": {
            "description": "Private authorization or quota storage unavailable; retry later.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "x-required-permissions": [
          "discovery.read"
        ]
      }
    },
    "/oauth/register": {
      "post": {
        "tags": [
          "Sandbox OAuth"
        ],
        "operationId": "registerPmaControlSandboxClient",
        "summary": "Register an expiring sandbox OAuth client",
        "description": "RFC7591 open registration for synthetic data only. Send grant_types=[\"client_credentials\"], response_types=[] and optional least-privilege scope. Client credentials expire after 24 hours; registration is rate limited. No customer access, contact-sales form or payment is involved.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true,
                "required": [
                  "grant_types",
                  "response_types"
                ],
                "properties": {
                  "grant_types": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 1,
                    "items": {
                      "type": "string",
                      "enum": [
                        "client_credentials"
                      ]
                    }
                  },
                  "response_types": {
                    "type": "array",
                    "maxItems": 0,
                    "items": {
                      "type": "string"
                    }
                  },
                  "token_endpoint_auth_method": {
                    "type": "string",
                    "enum": [
                      "client_secret_basic"
                    ],
                    "default": "client_secret_basic"
                  },
                  "scope": {
                    "type": "string",
                    "default": "sandbox.servers.read",
                    "description": "Space-separated sandbox.servers.read and/or sandbox.identity.read. Defaults to sandbox.servers.read."
                  }
                }
              },
              "example": {
                "grant_types": [
                  "client_credentials"
                ],
                "response_types": [],
                "scope": "sandbox.servers.read"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successful register an expiring sandbox oauth client.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "client_id",
                    "client_secret",
                    "client_id_issued_at",
                    "client_secret_expires_at",
                    "grant_types",
                    "response_types",
                    "token_endpoint_auth_method",
                    "scope"
                  ],
                  "properties": {
                    "client_id": {
                      "type": "string"
                    },
                    "client_secret": {
                      "type": "string"
                    },
                    "client_id_issued_at": {
                      "type": "integer"
                    },
                    "client_secret_expires_at": {
                      "type": "integer"
                    },
                    "grant_types": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "response_types": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "token_endpoint_auth_method": {
                      "type": "string"
                    },
                    "scope": {
                      "type": "string"
                    }
                  }
                },
                "examples": {
                  "illustrative": {
                    "summary": "Illustrative typed response. Credential values are nonfunctional examples.",
                    "value": {
                      "client_id": "ILLUSTRATIVE_SANDBOX_CLIENT_ID",
                      "client_secret": "NONFUNCTIONAL_EXAMPLE_SECRET",
                      "client_id_issued_at": 1792886400,
                      "client_secret_expires_at": 1792972800,
                      "grant_types": [
                        "client_credentials"
                      ],
                      "response_types": [],
                      "token_endpoint_auth_method": "client_secret_basic",
                      "scope": "sandbox.servers.read"
                    }
                  }
                }
              }
            },
            "headers": {
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or registration metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "error",
                    "error_description"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "error_description": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "405": {
            "description": "Use POST; other methods are not supported.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "error",
                    "error_description"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "error_description": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "Allow": {
                "description": "POST",
                "schema": {
                  "type": "string",
                  "const": "POST"
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "503": {
            "description": "Authorization temporarily unavailable; retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "error",
                    "error_description"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "error_description": {
                      "type": "string"
                    }
                  }
                }
              },
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "429": {
            "description": "Client quota exhausted; wait for Retry-After seconds.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before making another request.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/oauth/token": {
      "post": {
        "tags": [
          "Sandbox OAuth"
        ],
        "operationId": "issuePmaControlSandboxToken",
        "summary": "Issue a scoped sandbox Bearer token",
        "description": "RFC6749 client_credentials grant over HTTPS, authenticated exclusively with client_secret_basic. Request a subset of the client scopes. Tokens expire after at most 600 seconds, never later than the client secret, and no refresh token is issued. Unknown request parameters are ignored; duplicate parameters are rejected.",
        "security": [
          {
            "SandboxClientBasic": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "additionalProperties": true,
                "required": [
                  "grant_type"
                ],
                "properties": {
                  "grant_type": {
                    "type": "string",
                    "enum": [
                      "client_credentials"
                    ]
                  },
                  "scope": {
                    "type": "string",
                    "description": "Space-separated subset of the scopes granted to this client."
                  }
                }
              },
              "example": {
                "grant_type": "client_credentials",
                "scope": "sandbox.servers.read"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful issue a scoped sandbox bearer token.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "access_token",
                    "token_type",
                    "expires_in",
                    "scope"
                  ],
                  "properties": {
                    "access_token": {
                      "type": "string"
                    },
                    "token_type": {
                      "type": "string",
                      "const": "Bearer"
                    },
                    "expires_in": {
                      "type": "integer",
                      "minimum": 1,
                      "maximum": 600
                    },
                    "scope": {
                      "type": "string"
                    }
                  }
                },
                "examples": {
                  "illustrative": {
                    "summary": "Illustrative typed response. Credential values are nonfunctional examples.",
                    "value": {
                      "access_token": "NONFUNCTIONAL_EXAMPLE_ACCESS_TOKEN",
                      "token_type": "Bearer",
                      "expires_in": 600,
                      "scope": "sandbox.servers.read"
                    }
                  }
                }
              }
            },
            "headers": {
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or registration metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "error",
                    "error_description"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "error_description": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "405": {
            "description": "Use POST; other methods are not supported.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "error",
                    "error_description"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "error_description": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "Allow": {
                "description": "POST",
                "schema": {
                  "type": "string",
                  "const": "POST"
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "503": {
            "description": "Authorization temporarily unavailable; retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "error",
                    "error_description"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "error_description": {
                      "type": "string"
                    }
                  }
                }
              },
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "429": {
            "description": "Client quota exhausted; wait for Retry-After seconds.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before making another request.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or expired client credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "error",
                    "error_description"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "error_description": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "WWW-Authenticate": {
                "description": "HTTP Basic sandbox client challenge.",
                "schema": {
                  "type": "string"
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/onboarding": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "operationId": "getPmaControlSandboxOnboarding",
        "summary": "Discover free self-service sandbox onboarding",
        "description": "Return a machine-readable zero-account onboarding guide with anonymous and scoped synthetic sandbox endpoints, RFC7591 registration request, token endpoint, real credential lifetimes and official Homebrew CLI installation. Free sandbox credentials do not grant production or customer access.",
        "security": [],
        "responses": {
          "200": {
            "description": "Executable synthetic sandbox onboarding instructions.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "product",
                    "environment",
                    "free",
                    "customer_data",
                    "signup_required",
                    "production_keys_available",
                    "anonymous_sandbox_url",
                    "authorization_server_metadata",
                    "protected_resource_metadata",
                    "registration",
                    "token",
                    "scopes",
                    "protected_resources",
                    "cli"
                  ],
                  "properties": {
                    "product": {
                      "type": "string"
                    },
                    "environment": {
                      "type": "string"
                    },
                    "free": {
                      "type": "boolean"
                    },
                    "customer_data": {
                      "type": "boolean"
                    },
                    "signup_required": {
                      "type": "boolean"
                    },
                    "production_keys_available": {
                      "type": "boolean"
                    },
                    "anonymous_sandbox_url": {
                      "type": "string"
                    },
                    "authorization_server_metadata": {
                      "type": "string"
                    },
                    "protected_resource_metadata": {
                      "type": "string"
                    },
                    "registration": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "endpoint",
                        "method",
                        "content_type",
                        "request",
                        "client_secret_lifetime_seconds"
                      ],
                      "properties": {
                        "endpoint": {
                          "type": "string"
                        },
                        "method": {
                          "type": "string"
                        },
                        "content_type": {
                          "type": "string"
                        },
                        "request": {
                          "type": "object",
                          "additionalProperties": false,
                          "required": [
                            "grant_types",
                            "response_types",
                            "scope"
                          ],
                          "properties": {
                            "grant_types": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            },
                            "response_types": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            },
                            "scope": {
                              "type": "string"
                            }
                          }
                        },
                        "client_secret_lifetime_seconds": {
                          "type": "integer",
                          "minimum": 0
                        }
                      }
                    },
                    "token": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "endpoint",
                        "method",
                        "content_type",
                        "grant_type",
                        "client_authentication",
                        "maximum_lifetime_seconds"
                      ],
                      "properties": {
                        "endpoint": {
                          "type": "string"
                        },
                        "method": {
                          "type": "string"
                        },
                        "content_type": {
                          "type": "string"
                        },
                        "grant_type": {
                          "type": "string"
                        },
                        "client_authentication": {
                          "type": "string"
                        },
                        "maximum_lifetime_seconds": {
                          "type": "integer",
                          "minimum": 0
                        }
                      }
                    },
                    "scopes": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "sandbox.servers.read",
                        "sandbox.identity.read"
                      ],
                      "properties": {
                        "sandbox.servers.read": {
                          "type": "string"
                        },
                        "sandbox.identity.read": {
                          "type": "string"
                        }
                      }
                    },
                    "protected_resources": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                          "url",
                          "required_scope"
                        ],
                        "properties": {
                          "url": {
                            "type": "string"
                          },
                          "required_scope": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "cli": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "metadata_url",
                        "tap_url",
                        "install_commands"
                      ],
                      "properties": {
                        "metadata_url": {
                          "type": "string"
                        },
                        "tap_url": {
                          "type": "string"
                        },
                        "install_commands": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "illustrative": {
                    "summary": "Illustrative typed response. Credential values are nonfunctional examples.",
                    "value": {
                      "product": "PmaControl",
                      "environment": "sandbox",
                      "free": true,
                      "customer_data": false,
                      "signup_required": false,
                      "production_keys_available": false,
                      "anonymous_sandbox_url": "https://www.pmacontrol.com/api/v1/sandbox/servers",
                      "authorization_server_metadata": "https://www.pmacontrol.com/.well-known/oauth-authorization-server",
                      "protected_resource_metadata": "https://www.pmacontrol.com/.well-known/oauth-protected-resource",
                      "registration": {
                        "endpoint": "https://www.pmacontrol.com/oauth/register",
                        "method": "POST",
                        "content_type": "application/json",
                        "request": {
                          "grant_types": [
                            "client_credentials"
                          ],
                          "response_types": [],
                          "scope": "sandbox.servers.read"
                        },
                        "client_secret_lifetime_seconds": 86400
                      },
                      "token": {
                        "endpoint": "https://www.pmacontrol.com/oauth/token",
                        "method": "POST",
                        "content_type": "application/x-www-form-urlencoded",
                        "grant_type": "client_credentials",
                        "client_authentication": "client_secret_basic",
                        "maximum_lifetime_seconds": 600
                      },
                      "scopes": {
                        "sandbox.servers.read": "Read fixed synthetic server metrics.",
                        "sandbox.identity.read": "Read sandbox client identity and granted scopes."
                      },
                      "protected_resources": [
                        {
                          "url": "https://www.pmacontrol.com/api/v1/sandbox/authorized-servers",
                          "required_scope": "sandbox.servers.read"
                        },
                        {
                          "url": "https://www.pmacontrol.com/api/v1/sandbox/identity",
                          "required_scope": "sandbox.identity.read"
                        }
                      ],
                      "cli": {
                        "metadata_url": "https://www.pmacontrol.com/downloads/cli/release.json",
                        "tap_url": "https://www.pmacontrol.com/downloads/homebrew-agent.git",
                        "install_commands": [
                          "brew tap pmacontrol/agent https://www.pmacontrol.com/downloads/homebrew-agent.git",
                          "brew install pmacontrol/agent/pmacontrol-agent"
                        ]
                      }
                    }
                  }
                }
              }
            },
            "headers": {
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameter",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 policy: public-api; 300 requests per 60-second fixed window per client IP.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Structured field reporting policy, remaining requests (r) and reset delay in seconds (t).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Compatibility quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "description": "Compatibility remaining quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Reset": {
                "description": "Compatibility reset delay, in seconds; not a Unix timestamp.",
                "schema": {
                  "type": "string"
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 policy: public-api; 300 requests per 60-second fixed window per client IP.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Structured field reporting policy, remaining requests (r) and reset delay in seconds (t).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Compatibility quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "description": "Compatibility remaining quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Reset": {
                "description": "Compatibility reset delay, in seconds; not a Unix timestamp.",
                "schema": {
                  "type": "string"
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 policy: public-api; 300 requests per 60-second fixed window per client IP.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Structured field reporting policy, remaining requests (r) and reset delay in seconds (t).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Compatibility quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "description": "Compatibility remaining quota field.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Reset": {
                "description": "Compatibility reset delay, in seconds; not a Unix timestamp.",
                "schema": {
                  "type": "string"
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "429": {
            "description": "Client quota exhausted; wait for Retry-After seconds.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before making another request.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              },
              "Link": {
                "description": "Policy and migration documentation (rel=deprecation) plus the OpenAPI contract (rel=service-desc). Deprecation and Sunset dates are emitted only for actually scheduled retirements.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "message",
                    "resolution"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri-reference"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer",
                      "minimum": 400,
                      "maximum": 599
                    },
                    "detail": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "resolution": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "x-required-permissions": [
          "discovery.read"
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "Capabilities": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "product",
          "api_version",
          "access",
          "documentation_url",
          "openapi_url"
        ],
        "properties": {
          "product": {
            "type": "string",
            "const": "PmaControl"
          },
          "api_version": {
            "type": "string",
            "const": "1.1.0"
          },
          "access": {
            "type": "string",
            "const": "public-read-only"
          },
          "documentation_url": {
            "type": "string",
            "format": "uri"
          },
          "openapi_url": {
            "type": "string",
            "format": "uri"
          }
        },
        "description": "Identity of this public discovery API; does not report production health."
      },
      "Permissions": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "public_api",
          "installation_api",
          "oauth"
        ],
        "properties": {
          "public_api": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "authentication",
              "permissions",
              "customer_data",
              "credential_required"
            ],
            "properties": {
              "authentication": {
                "type": "string"
              },
              "permissions": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "customer_data": {
                "type": "boolean"
              },
              "credential_required": {
                "type": "boolean"
              }
            }
          },
          "installation_api": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "authentication",
              "availability",
              "source_revision",
              "permissions"
            ],
            "properties": {
              "authentication": {
                "type": "string"
              },
              "availability": {
                "type": "string"
              },
              "source_revision": {
                "type": "string"
              },
              "permissions": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "backup.read",
                  "backup.plan",
                  "backup.operate",
                  "clickhouse.route.operate"
                ],
                "properties": {
                  "backup.read": {
                    "type": "string"
                  },
                  "backup.plan": {
                    "type": "string"
                  },
                  "backup.operate": {
                    "type": "string"
                  },
                  "clickhouse.route.operate": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "oauth": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "available",
              "reason",
              "issuer",
              "token_endpoint",
              "registration_endpoint",
              "scopes_supported"
            ],
            "properties": {
              "available": {
                "type": "boolean"
              },
              "reason": {
                "type": "string"
              },
              "issuer": {
                "type": "string",
                "format": "uri"
              },
              "token_endpoint": {
                "type": "string",
                "format": "uri"
              },
              "registration_endpoint": {
                "type": "string",
                "format": "uri"
              },
              "scopes_supported": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        },
        "description": "Public and deployment-dependent installation permissions, plus real synthetic sandbox OAuth scope declarations. Sandbox credentials never grant installation permissions."
      },
      "Problem": {
        "type": "object",
        "additionalProperties": false,
        "description": "RFC 9457 problem details with stable code, message and resolution extensions.",
        "required": [
          "type",
          "title",
          "status",
          "detail",
          "code",
          "message",
          "resolution"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri-reference"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer",
            "minimum": 400,
            "maximum": 599
          },
          "detail": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "resolution": {
            "type": "string"
          }
        }
      },
      "DocumentationIndex": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "language",
          "items"
        ],
        "properties": {
          "language": {
            "type": "string",
            "enum": [
              "fr",
              "en",
              "pl",
              "ru",
              "zh",
              "ar"
            ]
          },
          "items": {
            "type": "array",
            "maxItems": 64,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "id",
                "title",
                "url"
              ],
              "properties": {
                "id": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          }
        },
        "description": "A bounded catalog of public guide URLs."
      },
      "SandboxServers": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "environment",
          "synthetic",
          "read_only",
          "servers"
        ],
        "properties": {
          "environment": {
            "type": "string",
            "const": "sandbox"
          },
          "synthetic": {
            "type": "boolean",
            "const": true
          },
          "read_only": {
            "type": "boolean",
            "const": true
          },
          "servers": {
            "type": "array",
            "minItems": 2,
            "maxItems": 2,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "id",
                "engine",
                "role",
                "replication_lag_seconds",
                "queries_per_second"
              ],
              "properties": {
                "id": {
                  "type": "string"
                },
                "engine": {
                  "type": "string",
                  "enum": [
                    "MariaDB",
                    "MySQL"
                  ]
                },
                "role": {
                  "type": "string",
                  "enum": [
                    "primary",
                    "replica"
                  ]
                },
                "replication_lag_seconds": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "Illustrative lag in seconds."
                },
                "queries_per_second": {
                  "type": "number",
                  "minimum": 0,
                  "description": "Illustrative queries per second."
                }
              }
            }
          }
        },
        "description": "Static synthetic server metrics for read-only integration tests."
      },
      "SandboxClient": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "client_id",
          "client_secret",
          "client_id_issued_at",
          "client_secret_expires_at",
          "grant_types",
          "response_types",
          "token_endpoint_auth_method",
          "scope"
        ],
        "properties": {
          "client_id": {
            "type": "string"
          },
          "client_secret": {
            "type": "string"
          },
          "client_id_issued_at": {
            "type": "integer"
          },
          "client_secret_expires_at": {
            "type": "integer"
          },
          "grant_types": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "response_types": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "token_endpoint_auth_method": {
            "type": "string"
          },
          "scope": {
            "type": "string"
          }
        }
      },
      "SandboxToken": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "access_token",
          "token_type",
          "expires_in",
          "scope"
        ],
        "properties": {
          "access_token": {
            "type": "string"
          },
          "token_type": {
            "type": "string",
            "const": "Bearer"
          },
          "expires_in": {
            "type": "integer",
            "minimum": 1,
            "maximum": 600
          },
          "scope": {
            "type": "string"
          }
        }
      },
      "OAuthError": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "error",
          "error_description"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "error_description": {
            "type": "string"
          }
        }
      },
      "SandboxIdentity": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "environment",
          "synthetic",
          "read_only",
          "client_id",
          "scopes",
          "expires_at"
        ],
        "properties": {
          "environment": {
            "type": "string",
            "const": "sandbox"
          },
          "synthetic": {
            "type": "boolean",
            "const": true
          },
          "read_only": {
            "type": "boolean",
            "const": true
          },
          "client_id": {
            "type": "string"
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "expires_at": {
            "type": "integer"
          }
        }
      },
      "Onboarding": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "product",
          "environment",
          "free",
          "customer_data",
          "signup_required",
          "production_keys_available",
          "anonymous_sandbox_url",
          "authorization_server_metadata",
          "protected_resource_metadata",
          "registration",
          "token",
          "scopes",
          "protected_resources",
          "cli"
        ],
        "properties": {
          "product": {
            "type": "string"
          },
          "environment": {
            "type": "string"
          },
          "free": {
            "type": "boolean"
          },
          "customer_data": {
            "type": "boolean"
          },
          "signup_required": {
            "type": "boolean"
          },
          "production_keys_available": {
            "type": "boolean"
          },
          "anonymous_sandbox_url": {
            "type": "string"
          },
          "authorization_server_metadata": {
            "type": "string"
          },
          "protected_resource_metadata": {
            "type": "string"
          },
          "registration": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "endpoint",
              "method",
              "content_type",
              "request",
              "client_secret_lifetime_seconds"
            ],
            "properties": {
              "endpoint": {
                "type": "string"
              },
              "method": {
                "type": "string"
              },
              "content_type": {
                "type": "string"
              },
              "request": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "grant_types",
                  "response_types",
                  "scope"
                ],
                "properties": {
                  "grant_types": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "response_types": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "scope": {
                    "type": "string"
                  }
                }
              },
              "client_secret_lifetime_seconds": {
                "type": "integer",
                "minimum": 0
              }
            }
          },
          "token": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "endpoint",
              "method",
              "content_type",
              "grant_type",
              "client_authentication",
              "maximum_lifetime_seconds"
            ],
            "properties": {
              "endpoint": {
                "type": "string"
              },
              "method": {
                "type": "string"
              },
              "content_type": {
                "type": "string"
              },
              "grant_type": {
                "type": "string"
              },
              "client_authentication": {
                "type": "string"
              },
              "maximum_lifetime_seconds": {
                "type": "integer",
                "minimum": 0
              }
            }
          },
          "scopes": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "sandbox.servers.read",
              "sandbox.identity.read"
            ],
            "properties": {
              "sandbox.servers.read": {
                "type": "string"
              },
              "sandbox.identity.read": {
                "type": "string"
              }
            }
          },
          "protected_resources": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "url",
                "required_scope"
              ],
              "properties": {
                "url": {
                  "type": "string"
                },
                "required_scope": {
                  "type": "string"
                }
              }
            }
          },
          "cli": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "metadata_url",
              "tap_url",
              "install_commands"
            ],
            "properties": {
              "metadata_url": {
                "type": "string"
              },
              "tap_url": {
                "type": "string"
              },
              "install_commands": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "PmaControlSandboxOAuth": {
        "type": "oauth2",
        "description": "Optional OAuth client_credentials for the synthetic sandbox only. Self-register a confidential client at /oauth/register. No user login, customer access, production API key or OpenID Connect identity is provided.",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://www.pmacontrol.com/oauth/token",
            "scopes": {
              "sandbox.servers.read": "Read fixed synthetic MariaDB / MySQL server metrics.",
              "sandbox.identity.read": "Read the authenticated sandbox client identity and granted scopes."
            }
          }
        }
      },
      "SandboxClientBasic": {
        "type": "http",
        "scheme": "basic",
        "description": "Expiring sandbox client_id and client_secret issued by /oauth/register; use only over HTTPS."
      }
    }
  },
  "x-permissions": {
    "discovery.read": "Anonymous read-only access to public product metadata; never grants installation access."
  },
  "externalDocs": {
    "description": "PmaControl API versioning and deprecation policy: minimum 90-day notice, with documented urgent security/legal exceptions.",
    "url": "https://www.pmacontrol.com/developers#api-versioning"
  },
  "x-deprecation-policy": {
    "url": "https://www.pmacontrol.com/api-policy.json",
    "minimum_notice_days": 90,
    "current_status": "active"
  }
}
