{"openapi":"3.1.0","info":{"title":"zReports Data API","version":"1.0.0","description":"The official records of every US health facility, for people, employers and AI agents.\n\nEvery figure is the government's own, quoted with its source, version and date. Where the file is silent, so are we.\n\nMCP endpoint for Claude, ChatGPT and any agent: https://api.zreports.org/mcp. Terms: https://api.zreports.org/api/data/terms.","contact":{"email":"data@zreports.org"}},"servers":[{"url":"https://api.zreports.org"}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"Optional. Without a key the anonymous tier applies."}},"schemas":{"Envelope":{"type":"object","properties":{"ok":{"type":"boolean"},"tool":{"type":"string"},"answer":{"type":"object"},"source":{"type":"object","nullable":true},"version":{"type":"string","nullable":true},"as_of":{"type":"string","nullable":true},"limitations":{"type":"array","items":{"type":"string"}},"zreports_url":{"type":"string","nullable":true},"attribution":{"type":"string","nullable":true},"accuracy":{"type":"string"}},"required":["ok","tool","answer","limitations","accuracy"]}}},"paths":{"/api/data/find":{"get":{"operationId":"find_facility","summary":"Find US health facilities in the zReports facility file by name words, city, state, zip or category (hospital, nursing, asc, psych, rehab, hospice, dialysis, homehealth, fertility, addiction, daycare).","description":"Find US health facilities in the zReports facility file by name words, city, state, zip or category (hospital, nursing, asc, psych, rehab, hospice, dialysis, homehealth, fertility, addiction, daycare). Returns matches with the facility_id to pass to get_record or compare. \"no match\" is an answer: the facility is not in the publisher's file.","parameters":[{"name":"name","in":"query","required":false,"description":"facility name, or part of it","schema":{"type":"string"}},{"name":"city","in":"query","required":false,"description":"","schema":{"type":"string"}},{"name":"state","in":"query","required":false,"description":"two letter state code","schema":{"type":"string"}},{"name":"zip","in":"query","required":false,"description":"five digit zip","schema":{"type":"string"}},{"name":"category","in":"query","required":false,"description":"one of hospital, nursing, asc, psych, rehab, hospice, dialysis, homehealth, fertility, addiction, daycare, skydive, balloon, airtour","schema":{"type":"string"}}],"security":[{"apiKey":[]},{}],"responses":{"200":{"description":"the envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"404":{"description":"no match (still an envelope)"},"429":{"description":"tier limit reached"}}}},"/api/data/record/{facility_id}":{"get":{"operationId":"get_record","summary":"Return the official records of one facility: the highlight lines, the publisher's row verbatim (official_record), the score and grade with the published rule, alternatives nearby in the same category, and the source, version and as_of date.","description":"Return the official records of one facility: the highlight lines, the publisher's row verbatim (official_record), the score and grade with the published rule, alternatives nearby in the same category, and the source, version and as_of date. Lines the publisher does not carry read \"not published\".","parameters":[{"name":"facility_id","in":"path","required":true,"description":"facility_id from find_facility (for example HOSP-050309, ASC-05C0001234, NH-055123, HOS-051500, DIA-052500, HHA-057000, IVF-1234)","schema":{"type":"string"}}],"security":[{"apiKey":[]},{}],"responses":{"200":{"description":"the envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"404":{"description":"no match (still an envelope)"},"429":{"description":"tier limit reached"}}}},"/api/data/company":{"get":{"operationId":"get_company","summary":"Return every facility the publisher lists under one chain or organization name, with counts by category and state, the average score, penalties and fines on record, and changes of ownership.","description":"Return every facility the publisher lists under one chain or organization name, with counts by category and state, the average score, penalties and fines on record, and changes of ownership. Use for health systems, nursing home chains, dialysis chains and surgery center operators.","parameters":[{"name":"name","in":"query","required":true,"description":"chain or organization name, or part of it","schema":{"type":"string"}},{"name":"state","in":"query","required":false,"description":"optional two letter state code","schema":{"type":"string"}}],"security":[{"apiKey":[]},{}],"responses":{"200":{"description":"the envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"404":{"description":"no match (still an envelope)"},"429":{"description":"tier limit reached"}}}},"/api/data/compare":{"get":{"operationId":"compare","summary":"Compare two to five facilities side by side on the same published fields: score, grade, status, ownership, beds, ratings, penalties, deficiencies where the publisher reports them.","description":"Compare two to five facilities side by side on the same published fields: score, grade, status, ownership, beds, ratings, penalties, deficiencies where the publisher reports them.","parameters":[{"name":"ids","in":"query","required":true,"description":"two to five facility_ids from find_facility","schema":{"type":"string","description":"comma separated"}}],"security":[{"apiKey":[]},{}],"responses":{"200":{"description":"the envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"404":{"description":"no match (still an envelope)"},"429":{"description":"tier limit reached"}}}},"/api/data/key":{"post":{"operationId":"issue_key","summary":"Get a free key, shown once.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"}},"required":["email"]}}}},"responses":{"200":{"description":"key"}}}}}}