{
  "openapi": "3.1.0",
  "info": {
    "title": "Lexiara",
    "version": "v1",
    "summary": "Provenance-backed EU/UK legislation, addressable to the provision.",
    "description": "Authoritative legislative text with provenance on every answer. Every provision payload carries an `authoritative` flag and a `provenance` block; derived data (transposition links, concept tags) carries method and confidence. Lexiara provides legal information, not legal advice.\n\nAn MCP server for AI agents is available at POST /mcp (see /docs/MCP.md in the repository); it exposes these same routes as tools under the same keys, quotas and metering."
  },
  "servers": [
    {
      "url": "https://legal-landscape-api.thomasmackie.workers.dev"
    }
  ],
  "security": [
    {
      "bearerKey": []
    },
    {
      "headerKey": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key as 'Authorization: Bearer <key>'."
      },
      "headerKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    },
    "schemas": {
      "Provenance": {
        "type": "object",
        "description": "Where this text came from and whether it may be relied on. Downstream users are contractually required to preserve this (Terms of Service §3).",
        "properties": {
          "sourceUrl": {
            "type": "string",
            "description": "The official publication this text was retrieved from."
          },
          "retrievedAt": {
            "type": "string",
            "description": "When Lexiara retrieved it."
          },
          "licence": {
            "type": "string",
            "description": "Licence the source is reused under (e.g. OGL v3.0)."
          },
          "contentSha256": {
            "type": "string",
            "description": "Hash of the retrieved content."
          },
          "isAuthoritative": {
            "type": "boolean",
            "description": "True when the text reproduces the cited official source. False text (e.g. machine translation) is a reading aid, never the operative law."
          }
        }
      }
    }
  },
  "paths": {
    "/v1/health": {
      "get": {
        "summary": "Liveness. Public; does not touch the database.",
        "security": [],
        "responses": {
          "200": {
            "description": "Service is up."
          }
        }
      }
    },
    "/v1/openapi.json": {
      "get": {
        "summary": "This document. Public.",
        "security": [],
        "responses": {
          "200": {
            "description": "The OpenAPI 3.1 description."
          }
        }
      }
    },
    "/v1/stats": {
      "get": {
        "summary": "Published accuracy and provenance statistics. Public.",
        "description": "Aggregate trust figures: provenance coverage, and classifier agreement measured against the publisher's own EuroVoc descriptors, with denominators and an honest statement of what is and is not being measured.",
        "security": [],
        "responses": {
          "200": {
            "description": "Aggregate statistics; no corpus text."
          }
        }
      }
    },
    "/v1/provisions": {
      "get": {
        "summary": "One provision's authoritative text, enriched",
        "description": "Text plus in-force window, repealed/prospective status, concept tags, transposition edges and provenance. `asAt` serves point-in-time law; `lang` serves a translation, flagged non-authoritative, with the original attached.",
        "parameters": [
          {
            "name": "work",
            "in": "query",
            "required": true,
            "description": "ELI URI of the instrument, e.g. http://www.legislation.gov.uk/id/ukpga/1994/23 (UK VAT Act 1994) or http://data.europa.eu/eli/dir/2006/112/oj (EU VAT Directive).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "eId",
            "in": "query",
            "required": true,
            "description": "Provision identifier: 'sec_4' (section 4), 'art_2__para_1' (article 2(1)), 'sch_8__part_ii__grp_1__para_1' (Schedule 8, Part II, Group 1, item 1).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "asAt",
            "in": "query",
            "required": false,
            "description": "Date YYYY-MM-DD: the law as it stood on that day.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "ISO 639 language, e.g. 'eng', 'fra' — a translation request.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The provision, with `authoritative`, `notice` and `provenance`."
          },
          "404": {
            "description": "No such work/eId (or not held — see /v1/coverage)."
          }
        }
      }
    },
    "/v1/search": {
      "get": {
        "summary": "Ranked full-text search over provision text",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Search terms, e.g. 'zero-rating of food'.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "jurisdiction",
            "in": "query",
            "required": false,
            "description": "ISO country filter, e.g. 'UK', 'FR', 'EU'.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Restrict to a text language, e.g. 'eng'.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum hits, default 10.",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Hits with work, eId, status, rank and provenance."
          }
        }
      }
    },
    "/v1/concepts/{conceptId}/provisions": {
      "get": {
        "summary": "Every provision tagged with a concept, cross-jurisdiction",
        "description": "The language-neutral join: line up EU and national law on one subject. Tags carry method + confidence; they are derived data.",
        "parameters": [
          {
            "name": "conceptId",
            "in": "path",
            "required": true,
            "description": "Namespaced concept id, e.g. 'eurovoc:4585' (VAT).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "jurisdiction",
            "in": "query",
            "required": false,
            "description": "ISO country filter, e.g. 'UK', 'FR', 'EU'.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "minConfidence",
            "in": "query",
            "required": false,
            "description": "Drop tags below this confidence (0–1).",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tagged provisions with tag metadata."
          }
        }
      }
    },
    "/v1/works/related": {
      "get": {
        "summary": "Instrument-level relationship graph",
        "parameters": [
          {
            "name": "eli",
            "in": "query",
            "required": true,
            "description": "ELI URI of the instrument.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "direction",
            "in": "query",
            "required": false,
            "description": "'in' = edges pointing at this work (default); 'out' = from it.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Typed edges with method, confidence, source."
          }
        }
      }
    },
    "/v1/provisions/history": {
      "get": {
        "summary": "A provision's version history across consolidations",
        "parameters": [
          {
            "name": "work",
            "in": "query",
            "required": true,
            "description": "ELI URI of the instrument, e.g. http://www.legislation.gov.uk/id/ukpga/1994/23 (UK VAT Act 1994) or http://data.europa.eu/eli/dir/2006/112/oj (EU VAT Directive).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "eId",
            "in": "query",
            "required": true,
            "description": "Provision identifier: 'sec_4' (section 4), 'art_2__para_1' (article 2(1)), 'sch_8__part_ii__grp_1__para_1' (Schedule 8, Part II, Group 1, item 1).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Prior and successor versions."
          },
          "404": {
            "description": "No such provision."
          }
        }
      }
    },
    "/v1/provisions/implementations": {
      "get": {
        "summary": "Article-level national implementations of an EU provision",
        "description": "DERIVED, not published by any authority. Every link carries method and confidence; treat links not marked method='human' as leads to verify.",
        "parameters": [
          {
            "name": "work",
            "in": "query",
            "required": true,
            "description": "ELI URI of the instrument, e.g. http://www.legislation.gov.uk/id/ukpga/1994/23 (UK VAT Act 1994) or http://data.europa.eu/eli/dir/2006/112/oj (EU VAT Directive).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "eId",
            "in": "query",
            "required": true,
            "description": "Provision identifier: 'sec_4' (section 4), 'art_2__para_1' (article 2(1)), 'sch_8__part_ii__grp_1__para_1' (Schedule 8, Part II, Group 1, item 1).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "jurisdiction",
            "in": "query",
            "required": false,
            "description": "ISO country filter, e.g. 'UK', 'FR', 'EU'.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "minConfidence",
            "in": "query",
            "required": false,
            "description": "Drop links below this confidence (0–1).",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Links, with an explicit derivation notice."
          }
        }
      }
    },
    "/v1/changes": {
      "get": {
        "summary": "Change feed — what the corpus observed",
        "description": "`detectedAt` is when Lexiara observed the change; legal in-force dates come only from the provision itself.",
        "parameters": [
          {
            "name": "jurisdiction",
            "in": "query",
            "required": false,
            "description": "ISO country filter, e.g. 'UK', 'FR', 'EU'.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "concept",
            "in": "query",
            "required": false,
            "description": "Restrict to one concept id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "description": "ISO date: only changes detected after this.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum items, default 50.",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Observed changes, newest first."
          }
        }
      }
    },
    "/v1/coverage": {
      "get": {
        "summary": "What the corpus holds, and how fresh",
        "description": "Call first when unsure whether Lexiara holds the law you need — absence of coverage means 'not held', never 'does not exist'.",
        "responses": {
          "200": {
            "description": "Per-source coverage and freshness."
          }
        }
      }
    }
  }
}