{
  "openapi": "3.1.0",
  "info": {
    "title": "Statbook API",
    "version": "1.0.1",
    "description": "UK statutory figures — corroborated against two official sources, cited, re-verified daily. Every response carries OGL attribution and a receipt block verifiable against the signed release manifest. Not advice: the API answers only \"what is/was statutory figure X, as of date D\".",
    "termsOfService": "https://statbook.co.uk/legal/terms/"
  },
  "servers": [
    {
      "url": "https://statbook.co.uk"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerKey": {
        "type": "http",
        "scheme": "bearer"
      },
      "headerKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key"
      }
    }
  },
  "paths": {
    "/v1/figures": {
      "get": {
        "summary": "Index of all figures with current values",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "jurisdiction",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Figure index"
          }
        }
      }
    },
    "/v1/figures/{id}": {
      "get": {
        "summary": "Full record including history and receipt",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Figure record"
          },
          "404": {
            "description": "Unknown figure id"
          }
        }
      }
    },
    "/v1/figures/{id}/current": {
      "get": {
        "summary": "Current value only",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current value"
          },
          "404": {
            "description": "Unknown figure id or no current value"
          }
        }
      }
    },
    "/v1/figures/{id}/asof/{date}": {
      "get": {
        "summary": "The value in force on a date (API key required)",
        "security": [
          {
            "bearerKey": []
          },
          {
            "headerKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "date",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Value in force on the date"
          },
          "401": {
            "description": "Missing/invalid API key"
          },
          "404": {
            "description": "No value in force on that date"
          }
        }
      }
    },
    "/v1/changes": {
      "get": {
        "summary": "Diff feed of releases (API key required)",
        "security": [
          {
            "bearerKey": []
          },
          {
            "headerKey": []
          }
        ],
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Releases since the date"
          },
          "401": {
            "description": "Missing/invalid API key"
          }
        }
      }
    },
    "/v1/releases/{version}/manifest": {
      "get": {
        "summary": "Signed release manifest (per-record hashes)",
        "parameters": [
          {
            "name": "version",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Manifest"
          }
        }
      }
    },
    "/v1/releases/{version}/dataset": {
      "get": {
        "summary": "Bulk dataset (latest release requires a key; prior releases and the public releases repo are free)",
        "security": [
          {
            "bearerKey": []
          },
          {
            "headerKey": []
          }
        ],
        "parameters": [
          {
            "name": "version",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Full dataset JSON"
          }
        }
      }
    }
  }
}