{
  "openapi": "3.1.0",
  "info": {
    "title": "Puntea administrativă API",
    "version": "2026.09.07-v1.2",
    "description": "Public, read-only resolver for the Romanian administrative crosswalk. A CUI checksum is syntactic and does not confirm current tax status."
  },
  "servers": [
    { "url": "https://mariuscomper.uk/puntea-administrativa" }
  ],
  "paths": {
    "/api/resolve": {
      "get": {
        "summary": "Resolve an administrative identifier",
        "description": "Provide one of cui, siruta, qid, postal/cp, or q. Results are returned from the published snapshot.",
        "parameters": [
          { "$ref": "#/components/parameters/Cui" },
          { "$ref": "#/components/parameters/Siruta" },
          { "$ref": "#/components/parameters/Qid" },
          { "$ref": "#/components/parameters/Postal" },
          { "$ref": "#/components/parameters/Query" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/ResolveResponse" },
          "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/api/checksum": {
      "get": {
        "summary": "Check a CUI control digit",
        "parameters": [
          { "$ref": "#/components/parameters/CuiRequired" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/ChecksumResponse" },
          "400": { "$ref": "#/components/responses/BadRequest" }
        }
      }
    },
    "/api/health": {
      "get": {
        "summary": "Read snapshot health metadata",
        "responses": {
          "200": { "$ref": "#/components/responses/HealthResponse" }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "Cui": { "name": "cui", "in": "query", "schema": { "type": "string" } },
      "CuiRequired": { "name": "cui", "in": "query", "required": true, "schema": { "type": "string" } },
      "Siruta": { "name": "siruta", "in": "query", "schema": { "type": "string" } },
      "Qid": { "name": "qid", "in": "query", "schema": { "type": "string", "pattern": "^Q[0-9]+$" } },
      "Postal": { "name": "postal", "in": "query", "schema": { "type": "string" } },
      "Query": { "name": "q", "in": "query", "schema": { "type": "string" } }
    },
    "responses": {
      "ResolveResponse": {
        "description": "Matching records from the current snapshot",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveResult" } } }
      },
      "ChecksumResponse": {
        "description": "Syntactic CUI checksum result",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChecksumResult" } } }
      },
      "HealthResponse": {
        "description": "Published data counts and release",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResult" } } }
      },
      "BadRequest": { "description": "Required query parameter is missing" },
      "ServerError": { "description": "Published catalog is temporarily unavailable" }
    },
    "schemas": {
      "ResolveResult": {
        "type": "object",
        "required": ["query", "count", "results"],
        "properties": {
          "query": { "type": "object" },
          "count": { "type": "integer" },
          "results": { "type": "array", "items": { "type": "object" } }
        }
      },
      "ChecksumResult": {
        "type": "object",
        "required": ["cui", "valid"],
        "properties": { "cui": { "type": "string" }, "valid": { "type": "boolean" } }
      },
      "HealthResult": {
        "type": "object",
        "required": ["status", "release", "dataset"],
        "properties": {
          "status": { "type": "string", "const": "ok" },
          "release": { "type": "string" },
          "dataset": { "type": "object" }
        }
      }
    }
  }
}