{
  "openapi": "3.1.0",
  "info": {
    "title": "Politrace snapshot API",
    "version": "1.0.0",
    "description": "Read-only Git-backed snapshots of sources and automated statutory assessments. Queries are not interpreted by the server."
  },
  "servers": [
    {
      "url": "/api"
    }
  ],
  "paths": {
    "/v1/{dataset}/index.json": {
      "get": {
        "operationId": "datasetIndex",
        "parameters": [
          {
            "name": "dataset",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "live"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dataset digest and collection URLs",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No such dataset, collection or record"
          }
        }
      }
    },
    "/v1/{dataset}/{collection}.json": {
      "get": {
        "operationId": "listRecords",
        "parameters": [
          {
            "name": "dataset",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "live"
              ]
            }
          },
          {
            "name": "collection",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "parties",
                "programs",
                "criteria",
                "laws",
                "impacts",
                "votes"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "{schema_version, dataset, total, items}",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No such dataset, collection or record"
          }
        }
      }
    },
    "/v1/{dataset}/{collection}/{id}.json": {
      "get": {
        "operationId": "getRecord",
        "parameters": [
          {
            "name": "dataset",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "live"
              ]
            }
          },
          {
            "name": "collection",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "parties",
                "programs",
                "criteria",
                "laws",
                "impacts",
                "votes"
              ]
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Canonical record",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No such dataset, collection or record"
          }
        }
      }
    },
    "/v1/{dataset}/programs/{id}/tree.json": {
      "get": {
        "operationId": "getTree",
        "parameters": [
          {
            "name": "dataset",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "live"
              ]
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tree, leaves and citation metadata",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No such dataset, collection or record"
          }
        }
      }
    },
    "/v1/{dataset}/{collection}/{id}/source.md": {
      "get": {
        "operationId": "getMarkdown",
        "parameters": [
          {
            "name": "dataset",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "live"
              ]
            }
          },
          {
            "name": "collection",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "programs",
                "laws"
              ]
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Verbatim extracted Markdown with PDF page markers",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "No such dataset, collection or record"
          }
        }
      }
    },
    "/v1/{dataset}/stats.json": {
      "get": {
        "operationId": "getStatistics",
        "parameters": [
          {
            "name": "dataset",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "live"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Statistics by programme and period",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No such dataset, collection or record"
          }
        }
      }
    },
    "/v1/{dataset}/search.json": {
      "get": {
        "operationId": "getSearchIndex",
        "parameters": [
          {
            "name": "dataset",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "live"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Searchable criteria index",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No such dataset, collection or record"
          }
        }
      }
    },
    "/v1/{dataset}/coverage.json": {
      "get": {
        "operationId": "getCoverage",
        "parameters": [
          {
            "name": "dataset",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "live"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Archive counts, source snapshots and explicit remaining law IDs",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No such dataset, collection or record"
          }
        }
      }
    },
    "/v1/{dataset}/voting-coverage.json": {
      "get": {
        "operationId": "getVotingCoverage",
        "parameters": [
          {
            "name": "dataset",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "live"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Per-law parliamentary lookup status, checked dates, unresolved ambiguity and source errors",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No such dataset, collection or record"
          }
        }
      }
    },
    "/v1/{dataset}/voting-summary.json": {
      "get": {
        "operationId": "getVotingSummary",
        "parameters": [
          {
            "name": "dataset",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "live"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Explicit coverage denominators and faction patterns; no party ranking",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No such dataset, collection or record"
          }
        }
      }
    },
    "/v1/{dataset}/voting-comparisons.json": {
      "get": {
        "operationId": "getVotingComparisons",
        "parameters": [
          {
            "name": "dataset",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "live"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Source-linked vote × criterion comparisons; possible tensions, not alleged promise breaches",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No such dataset, collection or record"
          }
        }
      }
    },
    "/v1/{dataset}/extraction.json": {
      "get": {
        "operationId": "getExtractionCoverage",
        "parameters": [
          {
            "name": "dataset",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "live"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Processed and remaining source leaves, for imported programmes only; not human review",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No such dataset, collection or record"
          }
        }
      }
    },
    "/v1/{dataset}/readings.json": {
      "get": {
        "operationId": "getReadingEditions",
        "parameters": [
          {
            "name": "dataset",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "live"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Versioned page-complete OCR reading editions; original evidence unchanged",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No such dataset, collection or record"
          }
        }
      }
    },
    "/v1/{dataset}/readings/{id}.json": {
      "get": {
        "operationId": "getReadingEdition",
        "parameters": [
          {
            "name": "dataset",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "live"
              ]
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OCR page text, original page numbers, provenance and warnings",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No such dataset, collection or record"
          }
        }
      }
    },
    "/v1/{dataset}/analysis.json": {
      "get": {
        "operationId": "getProductionProgress",
        "parameters": [
          {
            "name": "dataset",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "live"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "All-party coverage, pending/errors, reported costs and current checkpoint state",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No such dataset, collection or record"
          }
        }
      }
    },
    "/v1/{dataset}/analyses.json": {
      "get": {
        "operationId": "getAnalyses",
        "parameters": [
          {
            "name": "dataset",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "live"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Programme-scoped grouping and pair-level screening audits",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No such dataset, collection or record"
          }
        }
      }
    },
    "/v1/{dataset}/experiments.json": {
      "get": {
        "operationId": "getExperiments",
        "parameters": [
          {
            "name": "dataset",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "live"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Frozen grouping proposals, all-law coverage, pair dispositions and cumulative reported cost",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No such dataset, collection or record"
          }
        }
      }
    },
    "/v1/{dataset}/experiments/{id}.json": {
      "get": {
        "operationId": "getExperiment",
        "parameters": [
          {
            "name": "dataset",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "live"
              ]
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Programme-scoped experiment with all source criteria retained",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No such dataset, collection or record"
          }
        }
      }
    },
    "/v1/sources/bundestag-21.json": {
      "get": {
        "operationId": "getSourceCatalog",
        "responses": {
          "200": {
            "description": "21st Bundestag scope, programme URLs, PDF hashes and inspection notes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No such dataset, collection or record"
          }
        }
      }
    },
    "/v1/sources/laws-bundestag-21.json": {
      "get": {
        "operationId": "getArchiveInventory",
        "responses": {
          "200": {
            "description": "Dated, count-reconciled official archive inventory; not a fresh scan on every run",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No such dataset, collection or record"
          }
        }
      }
    }
  }
}