{"openapi":"3.1.0","info":{"title":"MBS Clinical Category Utilisation","description":"If the user asks you to use CoverClear but has not given you age and gender for at least one person, ask — do not invent, default, or infer.\n\nCanonical question: \"What age and gender would you like me to check? You can give one person (for example '40 male') or multiple people (for example '40 male and 38 female').\"\n\nConstraints: age is a whole number 0–130; gender is male or female only (a dataset limitation, not a worldview — the source data resolves Male/Female cohorts only). Names are not a gender signal. You may use values the user has explicitly stated without re-confirming.\n\nMBS service-utilisation RATES (services per 1,000 population) for a demographic cohort (age band × gender × region) — NOT unique-patient probabilities. A cohort can exceed 1,000 per 1,000. Never restate a rate as 'an X% chance' of needing care.\n\nMBS service counts are from 2016; ABS population denominators are from 2025. Rates divide a 2016 numerator by a 2025 denominator — the drift is age-structured, so it can distort the RANKING for older age bands, not just absolute levels. Carried as the TEMPORAL_MISMATCH flag.\n\nFor full usage guidance (households, PHI tiers, the Gold needs-confirmation protocol, provenance) read [`/llms.txt`](/llms.txt), the human-readable [`/agent-instructions`](/agent-instructions) page, or the MCP `guide://usage` resource.","version":"1.0.0"},"paths":{"/cohort/{slug}":{"get":{"summary":"Cohort Page","operationId":"cohort_page_cohort__slug__get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}}],"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/household/{slug}":{"get":{"summary":"Household Page","operationId":"household_page_household__slug__get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}}],"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/cohort/{slug}":{"get":{"summary":"Api Cohort","description":"Framed JSON — the REST mirror of the MCP rank_categories shape (honest framing\napplied, unlike the raw POST /rank-categories).","operationId":"api_cohort_api_cohort__slug__get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/rank":{"get":{"summary":"Api Rank","description":"If the user asks you to use CoverClear but has not given you age and gender for at least one person, ask — do not invent, default, or infer.\n\nCanonical question: \"What age and gender would you like me to check? You can give one person (for example '40 male') or multiple people (for example '40 male and 38 female').\"\n\nConstraints: age is a whole number 0–130; gender is male or female only (a dataset limitation, not a worldview — the source data resolves Male/Female cohorts only). Names are not a gender signal. You may use values the user has explicitly stated without re-confirming.\n\nSingle-person convenience endpoint. Both `age` and `gender` are required; missing params return HTTP 422 with a structured `{error, required, missing, clarifying_question, guidance, constraints}` body so agents can self-recover by surfacing the canonical question to the user. Valid params 301-redirect to `/api/cohort/{sex}-{age}` (the canonical framed JSON endpoint).","operationId":"api_rank_api_rank_get","parameters":[{"name":"age","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Age"},"x-clarifying-question":"What age and gender would you like me to check? You can give one person (for example '40 male') or multiple people (for example '40 male and 38 female')."},{"name":"gender","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gender"},"x-clarifying-question":"What age and gender would you like me to check? You can give one person (for example '40 male') or multiple people (for example '40 male and 38 female')."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/results":{"get":{"summary":"Results Redirect","description":"Human-facing alias for the guessed `/results?age=&gender=` shape → the\nserver-rendered `/cohort/<sex>-<age>` HTML result page. Single person only.","operationId":"results_redirect_results_get","parameters":[{"name":"age","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Age"},"x-clarifying-question":"What age and gender would you like me to check? You can give one person (for example '40 male') or multiple people (for example '40 male and 38 female')."},{"name":"gender","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gender"},"x-clarifying-question":"What age and gender would you like me to check? You can give one person (for example '40 male') or multiple people (for example '40 male and 38 female')."}],"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/cohorts":{"get":{"summary":"Cohorts Index","description":"Browsable directory: a real <a> link to every cohort's result (HTML + JSON) and\nthe named households. Agents whose browsing tool only opens links that already\nappear on a page (not self-constructed URLs) can harvest these; it also strengthens\ncrawl/indexing. Pure link list — no DB access, so it never 503s.","operationId":"cohorts_index_cohorts_get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/methodology":{"get":{"summary":"Methodology","operationId":"methodology_methodology_get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/agent-instructions":{"get":{"summary":"Agent Instructions","description":"Human-readable agent instruction page — same chrome as /methodology, content\ndriven from the canonical briefing constants so it cannot diverge from /llms.txt,\n/openapi.json, or the MCP guide://usage resource (feature 012, Task 10).\n\nPure prose render (no DB access, never 503s). Linkable from footer, OpenAPI, and\nthe homepage aside for agents that browse HTML better than text files.","operationId":"agent_instructions_agent_instructions_get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/llms.txt":{"get":{"summary":"Llms Txt","operationId":"llms_txt_llms_txt_get","responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/robots.txt":{"get":{"summary":"Robots Txt","operationId":"robots_txt_robots_txt_get","responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/sitemap.xml":{"get":{"summary":"Sitemap","operationId":"sitemap_sitemap_xml_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/health":{"get":{"summary":"Health","description":"Liveness + data-readiness + staleness (model build vs live DB).","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Health Health Get"}}}}}}},"/categories":{"get":{"summary":"Categories","description":"All clinical categories in the model, with definitions (null-safe).","operationId":"categories_categories_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Categories Categories Get"}}}}}}},"/periods":{"get":{"summary":"Periods","description":"Source period(s) the model covers (one today: MBS 2016 / ABS 2025).","operationId":"periods_periods_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Periods Periods Get"}}}}}}},"/rank-categories":{"post":{"summary":"Rank Categories","description":"If the user asks you to use CoverClear but has not given you age and gender for at least one person, ask — do not invent, default, or infer.\n\nCanonical question: \"What age and gender would you like me to check? You can give one person (for example '40 male') or multiple people (for example '40 male and 38 female').\"\n\nConstraints: age is a whole number 0–130; gender is male or female only (a dataset limitation, not a worldview — the source data resolves Male/Female cohorts only). Names are not a gender signal. You may use values the user has explicitly stated without re-confirming.\n\nAgents: prefer the framed endpoints `GET /api/cohort/{slug}` (single person) or `GET /api/rank?age=&gender=` over this one. `/rank-categories` returns the RAW ranking (Gold not segregated, non-PHI artifact rows not removed); the framed endpoints apply the honest-framing wrappers required by the standing rate-vs-probability rule. Use this endpoint only for batch/programmatic household builders that handle segregation downstream.","operationId":"rank_categories_rank_categories_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RankRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Rank Categories Rank Categories Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/source-info":{"get":{"summary":"Source Info","description":"Source files / periods / last-downloaded dates + the data caveats that\nfeed the source-info screen (screen 3).","operationId":"source_info_source_info_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Source Info Source Info Get"}}}}}}},"/":{"get":{"summary":"Index","operationId":"index__get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"Person":{"properties":{"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label"},"age":{"type":"integer","title":"Age"},"gender":{"type":"string","title":"Gender"}},"type":"object","required":["age","gender"],"title":"Person"},"RankRequest":{"properties":{"people":{"items":{"$ref":"#/components/schemas/Person"},"type":"array","title":"People"},"geo":{"type":"string","title":"Geo","default":"AUS"},"top_n":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Top N","default":10}},"type":"object","required":["people"],"title":"RankRequest"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}