{
  "openapi": "3.1.0",
  "info": {
    "title": "Kybriq ZKB Decision API",
    "version": "0.1.0",
    "description": "PLANNED contract (M1+). Not served yet. Will expose the same pure decision engine that powers the free calculator. Every response field carrying a legal claim will include `sources`: verbatim quote IDs resolvable via /llms.txt.",
    "x-status": "planned",
    "x-product": "Kybriq by Hexenkraft"
  },
  "paths": {
    "/api/v1/scope": {
      "post": {
        "summary": "Determine whether an organisation provides a regulated service and in which regime",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ScopeInput" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Decision (may be needs_review with missing-question list). Ambiguous inputs never return out_of_scope silently.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ZkbDecision" }
              }
            }
          },
          "400": { "description": "Out-of-vocabulary value or non-finite number → EngineInputError" }
        }
      }
    },
    "/api/v1/timeline": {
      "post": {
        "summary": "Dated obligation calendar from registration-decision delivery date",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["decisionDeliveredOn", "regime"],
                "properties": {
                  "decisionDeliveredOn": { "type": "string", "format": "date" },
                  "regime": { "enum": ["higher_regime", "lower_regime"] },
                  "transitionalSubject": { "type": "boolean" }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Timeline events with statutory/milestone/practice kinds and sources" } }
      }
    },
    "/api/v1/incident-clocks": {
      "post": {
        "summary": "§ 16 incident-reporting deadlines (duration-based, DST-safe)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["detectedAt"],
                "properties": {
                  "detectedAt": { "type": "string", "format": "date-time" },
                  "trustServices": { "type": "boolean", "default": false }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "initialReportDue (+24h) and notificationDue (+72h, trust: +24h)" } }
      }
    }
  },
  "components": {
    "schemas": {
      "ScopeInput": {
        "type": "object",
        "properties": {
          "serviceRow": { "type": "string", "description": "Annex row id of vyhláška 408/2025 Sb., or not_listed_review_manually" },
          "sector": { "type": "string", "description": "§ 4 odst. 1 písm. a) sector id" },
          "sizeClass": { "enum": ["micro", "small", "medium", "large"] },
          "simCards": { "type": "number", "minimum": 0 },
          "fixedLines": { "type": "number", "minimum": 0 },
          "revenueSharePct": { "type": "number", "minimum": 0 },
          "installedCapacityMw": { "type": "number", "minimum": 0, "description": "Total installed electrical capacity in MW (annex row 2.1 only)" },
          "servesNonConsumers": { "type": "boolean", "description": "Rows 16.13/16.14: provider has customers who are not consumers (having such customers, not serving them exclusively)" },
          "stateHealthProvider": { "type": "boolean" },
          "hasLinkedOrPartnerEnterprises": { "type": "boolean", "description": "Partner or linked enterprises per Rec. 2003/361 Art. 3; true means the size figures must be consolidated, which the engine does not compute; it returns needs_review" },
          "designatedUnderS5": { "type": "boolean" },
          "doraRegulated": { "type": "boolean" }
        }
      },
      "ZkbDecision": {
        "type": "object",
        "properties": {
          "outcome": {
            "enum": [
              "higher_regime",
              "lower_regime",
              "out_of_scope",
              "needs_review",
              "carve_out_dora"
            ]
          },
          "headline": { "type": "string" },
          "reasons": { "type": "array", "items": { "type": "string" } },
          "warnings": { "type": "array", "items": { "type": "string" } },
          "nextSteps": { "type": "array", "items": { "type": "string" } },
          "sources": { "type": "array", "items": { "type": "string" }, "description": "Corpus quote IDs" },
          "missing": { "type": "array", "items": { "type": "string" } }
        }
      }
    }
  }
}