{"openapi":"3.1.0","info":{"title":"ShortageSignal API","version":"1.0.0","description":"UK medicine shortage notices as structured, source-linked data. Open and keyless (fair use). Every record links its source document; fuzzy source dates are preserved as stated, never invented."},"servers":[{"url":"https://shortagesignal.co.uk"}],"paths":{"/api/v1/shortages":{"get":{"summary":"All tracked notices, newest change first","responses":{"200":{"description":"Envelope of notice records","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"service":{"type":"string"},"generated_at":{"type":"string","format":"date-time"},"count":{"type":"integer"},"docs":{"type":"string"},"source_note":{"type":"string"},"disclaimer":{"type":"string"}}},"results":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"notice_kind":{"type":"string","enum":["msn","msn_update","ssp_extension"]},"msn_ref":{"type":["string","null"]},"msn_ref_anomaly":{"type":"boolean","description":"true when the source itself carries a reference inconsistency — preserved, not corrected"},"tier":{"type":["integer","null"],"minimum":1,"maximum":4},"impact":{"type":["string","null"]},"date_of_issue":{"type":["string","null"],"format":"date"},"last_event_date":{"type":["string","null"],"format":"date"},"event_count":{"type":"integer"},"source_url":{"type":"string"}}}}}}}}}}}},"/api/v1/events":{"get":{"summary":"Change feed — poll with ?since= and never miss an update","parameters":[{"name":"since","in":"query","schema":{"type":"string","format":"date"},"description":"ISO date; return events on/after it"},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}}],"responses":{"200":{"description":"Envelope of timeline events","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"service":{"type":"string"},"generated_at":{"type":"string","format":"date-time"},"count":{"type":"integer"},"docs":{"type":"string"},"source_note":{"type":"string"},"disclaimer":{"type":"string"}}},"results":{"type":"array","items":{"type":"object","properties":{"event_type":{"type":"string","enum":["msn_issued","msn_updated","product_discontinued","ssp_issued","ssp_extended","ssp_expired","ssp_revoked"]},"event_date":{"type":"string","format":"date"},"title":{"type":["string","null"]},"msn_ref":{"type":["string","null"]},"tier":{"type":["integer","null"]},"ssp_number":{"type":["integer","null"]},"payload":{"type":"object"},"source_url":{"type":["string","null"]}}}}}}}}},"400":{"description":"Bad since/limit parameter"}}}},"/api/v1/ssps":{"get":{"summary":"Serious Shortage Protocols with extension counts and current expiry","responses":{"200":{"description":"Envelope of SSP summaries","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"service":{"type":"string"},"generated_at":{"type":"string","format":"date-time"},"count":{"type":"integer"},"docs":{"type":"string"},"source_note":{"type":"string"},"disclaimer":{"type":"string"}}},"results":{"type":"array","items":{"type":"object","properties":{"ssp_number":{"type":"integer"},"ssp_ref":{"type":"string"},"ssp_type":{"type":["string","null"]},"status":{"type":["string","null"],"enum":["active","expired","revoked",null]},"valid_from":{"type":["string","null"],"format":"date"},"current_expiry":{"type":["string","null"],"format":"date"},"extension_count":{"type":"integer"},"document_count":{"type":"integer"},"detail_url":{"type":"string"}}}}}}}}}}}}}}