{
  "openapi": "3.1.0",
  "info": {
    "title": "ADHD Helper Data API",
    "summary": "Read-only public data on UK adult ADHD: primary-sourced statistics, NHS prescribing and a content index.",
    "description": "Machine-readable access to ADHD Helper's UK adult ADHD data: most-quoted statistics (prevalence, assessment waiting times, Right to Choose, medication prescribing), each attributed to a named primary source (NHS, NICE, Royal College of Psychiatrists, NHSBSA, gov.uk); the NHSBSA English Prescribing Dataset series for the five licensed ADHD medicines; and a curated index of the site's answer pages. Read-only, no authentication, no PII, CC BY 4.0. Also exposed as an MCP server at /mcp (see /.well-known/mcp.json). YMYL: this is information, not medical advice and not a diagnosis. Only a registered clinician can diagnose or treat ADHD.",
    "version": "2026-06-12",
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    },
    "contact": {
      "name": "ADHD Helper",
      "url": "https://adhdhelper.co.uk/api/"
    }
  },
  "servers": [
    { "url": "https://adhdhelper.co.uk", "description": "Production" }
  ],
  "externalDocs": {
    "description": "Human-readable API documentation",
    "url": "https://adhdhelper.co.uk/api/"
  },
  "paths": {
    "/api/statistics": {
      "get": {
        "operationId": "listStatistics",
        "summary": "List live, primary-sourced UK adult ADHD statistics",
        "description": "Returns all live statistics, or a filtered subset when query params are supplied. Each figure is attributed to a named primary source. Information only, not medical advice.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Free-text match on the figure, claim, period and source.",
            "schema": { "type": "string" }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Filter by statistic category.",
            "schema": {
              "type": "string",
              "enum": ["prevalence", "access", "routes", "medication"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A list of statistics.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "schema_version": { "type": "string" },
                    "source": { "type": "string", "format": "uri" },
                    "license": { "type": "string", "format": "uri" },
                    "disclaimer": { "type": "string" },
                    "date_modified": { "type": "string", "format": "date" },
                    "count": { "type": "integer" },
                    "statistics": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Statistic" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/statistics/{id}": {
      "get": {
        "operationId": "getStatistic",
        "summary": "Get a single statistic by id",
        "description": "Returns one live statistic by its stable id (e.g. adult-prevalence).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "adult-prevalence"
          }
        ],
        "responses": {
          "200": {
            "description": "The matching statistic.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "schema_version": { "type": "string" },
                    "source": { "type": "string", "format": "uri" },
                    "license": { "type": "string", "format": "uri" },
                    "disclaimer": { "type": "string" },
                    "statistic": { "$ref": "#/components/schemas/Statistic" }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No live statistic matches the id.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/api/prescribing": {
      "get": {
        "operationId": "getPrescribingSnapshot",
        "summary": "NHSBSA ADHD medication prescribing series",
        "description": "Monthly NHS prescription items for the five licensed ADHD medicines (methylphenidate, lisdexamfetamine, atomoxetine, dexamfetamine, guanfacine) dispensed in primary care in England, from the NHSBSA English Prescribing Dataset (Open Government Licence v3.0). All ages, not adults only. Prescribing volume is not a diagnosis count. Information only, not medical advice.",
        "responses": {
          "200": {
            "description": "Prescribing snapshot and time series.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PrescribingSnapshot" }
              }
            }
          }
        }
      }
    },
    "/api/topics": {
      "get": {
        "operationId": "listTopics",
        "summary": "Index of ADHD Helper answer pages",
        "description": "Curated index of the main answer pages (assessment routes, understanding ADHD, living with ADHD, comparisons), so an agent can discover and cite the right page. Information only, not medical advice.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Free-text match on title, summary and category.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Content index.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "schema_version": { "type": "string" },
                    "source": { "type": "string", "format": "uri" },
                    "license": { "type": "string", "format": "uri" },
                    "disclaimer": { "type": "string" },
                    "count": { "type": "integer" },
                    "topics": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Topic" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Statistic": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "category": { "type": "string", "enum": ["prevalence", "access", "routes", "medication"] },
          "category_label": { "type": "string" },
          "value": { "type": "string" },
          "claim": { "type": "string" },
          "period": { "type": "string" },
          "source_name": { "type": "string" },
          "source_url": { "type": "string", "format": "uri" },
          "first_party": { "type": "boolean" },
          "page_url": { "type": "string", "format": "uri" }
        },
        "required": ["id", "category", "value", "claim", "source_name", "source_url"]
      },
      "Topic": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" },
          "title": { "type": "string" },
          "category": { "type": "string" },
          "summary": { "type": "string" },
          "url": { "type": "string", "format": "uri" }
        },
        "required": ["slug", "title", "url"]
      },
      "PrescribingMonth": {
        "type": "object",
        "properties": {
          "month": { "type": "string" },
          "totalItems": { "type": "integer" },
          "totalActualCost": { "type": "number" },
          "byChemical": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "items": { "type": "integer" },
                "actualCost": { "type": "number" }
              }
            }
          }
        }
      },
      "PrescribingSnapshot": {
        "type": "object",
        "properties": {
          "schema_version": { "type": "string" },
          "source": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "dataset_url": { "type": "string", "format": "uri" },
              "licence": { "type": "string" },
              "licence_url": { "type": "string", "format": "uri" },
              "coverage": { "type": "string" }
            }
          },
          "fetched_at": { "type": "string", "format": "date" },
          "chemicals": { "type": "array", "items": { "type": "string" } },
          "latest_month": { "type": "string" },
          "latest_totals": {
            "type": "object",
            "properties": {
              "items": { "type": "integer" },
              "actualCost": { "type": "number" }
            }
          },
          "year_ago_month": { "type": "string" },
          "yoy_items_change_pct": { "type": "number" },
          "months": { "type": "array", "items": { "$ref": "#/components/schemas/PrescribingMonth" } },
          "note": { "type": "string" },
          "page_url": { "type": "string", "format": "uri" },
          "license": { "type": "string", "format": "uri" },
          "disclaimer": { "type": "string" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string" },
          "detail": { "type": "string" }
        }
      }
    }
  }
}