{
  "openapi": "3.1.0",
  "info": {
    "title": "EDSO Public API",
    "version": "1.0.0",
    "description": "Programmatic access to the EDSO public register, specification, consultations and certificate verification. Reading is unauthenticated; write endpoints require an API key (request from the EDSO Geschäftsstelle).",
    "contact": {
      "name": "EDSO Geschäftsstelle",
      "email": "api@edso.eu"
    },
    "license": {
      "name": "CC-BY 4.0 (data)",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://edso-standard.eu",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "spec",
      "description": "EDSO specification metadata and versions."
    },
    {
      "name": "register",
      "description": "Public register of services, providers and audit bodies."
    },
    {
      "name": "verify",
      "description": "Cryptographic certificate verification."
    },
    {
      "name": "konsultationen",
      "description": "Public consultations."
    },
    {
      "name": "glossar",
      "description": "Glossary terms for tooltip integration."
    },
    {
      "name": "suche",
      "description": "Full-text search across the public site."
    }
  ],
  "paths": {
    "/api/v1/spec/current": {
      "get": {
        "tags": [
          "spec"
        ],
        "summary": "Metadata of the currently active specification.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SpecMetadata"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/spec/versions": {
      "get": {
        "tags": [
          "spec"
        ],
        "summary": "All published specification versions.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SpecVersionList"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/spec/{version}": {
      "get": {
        "tags": [
          "spec"
        ],
        "summary": "Full text of a specification version (JSON-LD).",
        "parameters": [
          {
            "name": "version",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Version identifier, e.g. v1.0"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SpecDocument"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/services": {
      "get": {
        "tags": [
          "register"
        ],
        "summary": "Paginated list of certified services.",
        "parameters": [
          {
            "name": "sektor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by Sektor."
          },
          {
            "name": "mindestlevel",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Minimum overall level (0–3)."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by status (gueltig, ausgesetzt, ...)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Page size (default 50, max 200)."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Pagination offset."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceList"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/services/{slug}": {
      "get": {
        "tags": [
          "register"
        ],
        "summary": "Single service record.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Service slug."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Service"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/anbieter": {
      "get": {
        "tags": [
          "register"
        ],
        "summary": "Paginated list of providers.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnbieterList"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/anbieter/{slug}": {
      "get": {
        "tags": [
          "register"
        ],
        "summary": "Single provider record.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Provider slug."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Anbieter"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/pruefstellen": {
      "get": {
        "tags": [
          "register"
        ],
        "summary": "Accredited audit bodies.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PruefstelleList"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/aenderungsprotokoll": {
      "get": {
        "tags": [
          "register"
        ],
        "summary": "Chronological change log of register events.",
        "parameters": [
          {
            "name": "typ",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by change type."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Page size (default 50)."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Pagination offset."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AenderungList"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/zertifikate/verify": {
      "post": {
        "tags": [
          "verify"
        ],
        "summary": "Verify a certificate cryptographically against the trust bundle.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "id"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "example": "EDSO-2026-00142"
                  },
                  "hash": {
                    "type": "string",
                    "description": "Optional SHA-256 hex of the canonical payload."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerifyResult"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/konsultationen": {
      "get": {
        "tags": [
          "konsultationen"
        ],
        "summary": "All consultations (running and closed).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KonsultationList"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/konsultationen/{slug}": {
      "get": {
        "tags": [
          "konsultationen"
        ],
        "summary": "Single consultation record.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Consultation slug."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Konsultation"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/glossar": {
      "get": {
        "tags": [
          "glossar"
        ],
        "summary": "All glossary terms.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GlossarList"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/suche": {
      "get": {
        "tags": [
          "suche"
        ],
        "summary": "Full-text search across the public site.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Search query."
          },
          {
            "name": "typ",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by entry type."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Page size (default 50)."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResult"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SpecMetadata": {
        "type": "object",
        "properties": {
          "version": {
            "type": "string"
          },
          "status": {
            "type": "string"
          }
        }
      },
      "SpecVersionList": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "SpecDocument": {
        "type": "object"
      },
      "Service": {
        "type": "object"
      },
      "ServiceList": {
        "type": "object"
      },
      "Anbieter": {
        "type": "object"
      },
      "AnbieterList": {
        "type": "object"
      },
      "PruefstelleList": {
        "type": "object"
      },
      "AenderungList": {
        "type": "object"
      },
      "VerifyResult": {
        "type": "object"
      },
      "KonsultationList": {
        "type": "object"
      },
      "Konsultation": {
        "type": "object"
      },
      "GlossarList": {
        "type": "object"
      },
      "SearchResult": {
        "type": "object"
      }
    }
  },
  "x-rate-limit": {
    "anonymous": "60 req/min",
    "authenticated": "1000 req/min"
  }
}