{
  "openapi": "3.1.1",
  "info": {
    "title": "BESA-AG — AIRL v2.0 & AI DATA Public Information API",
    "version": "2.0.0",
    "summary": "Read-only, zero-JS, cryptographically signed public AI DATA endpoints for BESA-AG.",
    "description": "Provides deterministic, provenance-bound entity envelopes, bitemporal facts, source snapshots, and localized JSON/Markdown representations for browsing AI agents."
  },
  "servers": [
    {
      "url": "https://besa-ag.be"
    }
  ],
  "paths": {
    "/ai/": {
      "get": {
        "operationId": "getAiDataIndexHtml",
        "summary": "Server-rendered HTML AI DATA overview",
        "responses": {
          "200": {
            "description": "HTML overview page"
          }
        }
      }
    },
    "/ai/company.json": {
      "get": {
        "operationId": "getCompanyJson",
        "summary": "Complete approved public company/website JSON (v1.0 & v2.0 compatible)",
        "responses": {
          "200": {
            "description": "Approved public company JSON"
          }
        }
      }
    },
    "/ai/company.md": {
      "get": {
        "operationId": "getCompanyMarkdown",
        "summary": "Clean Markdown equivalent of public company/website data",
        "responses": {
          "200": {
            "description": "Approved public Markdown"
          }
        }
      }
    },
    "/ai/entity.json": {
      "get": {
        "operationId": "getSignedEntityEnvelope",
        "summary": "AIRL v2.0 RFC 8785 JCS + Ed25519 signed ContextEnvelope",
        "responses": {
          "200": {
            "description": "Signed AIRL v2.0 ContextEnvelope"
          }
        }
      }
    },
    "/ai/facts.json": {
      "get": {
        "operationId": "getBitemporalFacts",
        "summary": "Bitemporal source-bound facts with valid_from/valid_to and recorded_from/recorded_to",
        "responses": {
          "200": {
            "description": "Bitemporal facts list"
          }
        }
      }
    },
    "/ai/graph.json": {
      "get": {
        "operationId": "getEvidenceClosedSubgraph",
        "summary": "Token-budgeted, evidence-closed entity relationship subgraph",
        "responses": {
          "200": {
            "description": "Evidence-closed subgraph"
          }
        }
      }
    },
    "/ai/sources.json": {
      "get": {
        "operationId": "getSourcesAndSnapshots",
        "summary": "First-party approved sources, SHA-256 file snapshots, and evidence bindings",
        "responses": {
          "200": {
            "description": "Provenance sources and snapshots"
          }
        }
      }
    },
    "/ai/changes.json": {
      "get": {
        "operationId": "getEntityChanges",
        "summary": "Bitemporal revision and supersession log",
        "responses": {
          "200": {
            "description": "Entity revision history"
          }
        }
      }
    },
    "/ai/marker.json": {
      "get": {
        "operationId": "getAirlMarkerRecord",
        "summary": "AIRL-CHK10/v1 deterministic public marker token and resolution map",
        "responses": {
          "200": {
            "description": "AIRL-CHK10/v1 marker record"
          }
        }
      }
    },
    "/ai/airl-keys.json": {
      "get": {
        "operationId": "getPublisherPublicKeys",
        "summary": "Ed25519 public key manifest for verifying entity.json signatures",
        "responses": {
          "200": {
            "description": "Publisher Ed25519 key manifest"
          }
        }
      }
    },
    "/.well-known/airl-keys.json": {
      "get": {
        "operationId": "getWellKnownPublisherPublicKeys",
        "summary": "RFC 8615 well-known Ed25519 public key manifest",
        "responses": {
          "200": {
            "description": "Publisher Ed25519 key manifest"
          }
        }
      }
    },
    "/a/{token}": {
      "get": {
        "operationId": "resolveShortMarkerToken",
        "summary": "Resolve an AIRL-CHK10/v1 short marker token URL",
        "responses": {
          "200": {
            "description": "Resolved signed ContextEnvelope or redirect metadata"
          },
          "400": {
            "description": "RFC 9457 Problem Details — Invalid token checksum"
          },
          "404": {
            "description": "RFC 9457 Problem Details — Unknown token"
          }
        }
      }
    },
    "/api/ai/v1/resolve/{token}": {
      "get": {
        "operationId": "resolveAirlTokenApi",
        "summary": "Resolve an AIRL-CHK10/v1 token with optional cross-layer fiducial verification",
        "responses": {
          "200": {
            "description": "Resolved token with trust_state (A1/A2/MISMATCH_WARNING)"
          },
          "400": {
            "description": "RFC 9457 Problem Details — Invalid token"
          },
          "404": {
            "description": "RFC 9457 Problem Details — Token not found"
          }
        }
      }
    },
    "/api/ai/v1/entity/{id}": {
      "get": {
        "operationId": "getDynamicEntityEnvelope",
        "summary": "Query an entity with dynamic topic, max_tokens budget, and bitemporal valid_at/known_at filtering",
        "responses": {
          "200": {
            "description": "Signed AIRL v2.0 ContextEnvelope"
          },
          "404": {
            "description": "RFC 9457 Problem Details — Entity not found"
          },
          "422": {
            "description": "RFC 9457 Problem Details — BUDGET_TOO_SMALL"
          }
        }
      }
    },
    "/api/ai/v1/search": {
      "get": {
        "operationId": "searchEntitiesHybridRrf",
        "summary": "Hybrid lexical BM25 + graph RRF search with bounded corrective retrieval self-repair",
        "responses": {
          "200": {
            "description": "Ranked search hits with RRF scores and corrective repair metadata"
          },
          "400": {
            "description": "RFC 9457 Problem Details — Missing query"
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "operationId": "postMcpJsonRpc",
        "summary": "Read-only Model Context Protocol (2026-07-28) JSON-RPC 2.0 endpoint",
        "responses": {
          "200": {
            "description": "JSON-RPC 2.0 response"
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "operationId": "getLlmsTxt",
        "summary": "Concise AI agent discovery index",
        "responses": {
          "200": {
            "description": "llms.txt discovery file"
          }
        }
      }
    }
  }
}
