{
  "openapi": "3.1.1",
  "info": {
    "title": "PmaControl Public Discovery API",
    "version": "1.0.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.",
    "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"
    }
  ],
  "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": {
                  "$ref": "#/components/schemas/Capabilities"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameter",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "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": {
                  "$ref": "#/components/schemas/Permissions"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameter",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/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": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "200": {
            "description": "Public documentation index",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocumentationIndex"
                }
              }
            }
          }
        }
      }
    },
    "/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": {
                  "$ref": "#/components/schemas/SandboxServers"
                },
                "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
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameter",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "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.0.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"
            ],
            "properties": {
              "available": {
                "type": "boolean"
              },
              "reason": {
                "type": "string"
              }
            }
          }
        },
        "description": "Verified public and installation permission boundaries. Installation scopes are not OAuth scopes."
      },
      "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."
      }
    }
  },
  "x-permissions": {
    "discovery.read": "Anonymous read-only access to public product metadata; never grants installation access."
  }
}