Data may be out of date. Our scheduled checks are behind: the last successful check of the sources finished 20 Oct 2026, 21:00 UTC (16 days ago), more than 36 hours ago. Checks normally run twice daily, so figures on this page may be out of date. See the service status.
ShortageSignal

← API

Developers

API changelog

Append-only. Nothing in a released version is removed or renamed; new fields are added beside the old ones and id is never replaced. Pollers built on v1.0 keep working without a change. The machine-readable contract is /api/openapi.json; the envelope reports its meta.schema_version.

v1.2 2026-09-30

Run status, search, identifiers, the weekly digest and the expected-back tracker

  • /api/v1/status: what the scheduled checks actually did, from the run log — observed run times, parked posts, gate state and the alerts mode.
  • /api/v1/search?q=: results grouped by kind (medicine pages, England notices, protocols, Scotland in its own group, discontinuations), each hit with why_matched.
  • /api/v1/identifiers: a brand or generic name matched to BNF chemical and SNOMED identifiers from NHSBSA open data (Open Government Licence), with the attribution the licence requires.
  • /api/v1/digest/latest.json and /api/v1/digest/{week}: the weekly digest as JSON, the same content as /digest/{week}.
  • Records on /api/v1/shortages gain expected_back_state, expected_back_window_end, expected_back_derived_from, expected_back_lines_stated and expected_back_lines_passed; the list takes an expected_back_state filter.
  • Nothing from 1.1 was removed or renamed.

v1.1 2026-09-30(contract fixed; served from the deployment that carries this page)

Stable ids, capture timestamps, provenance on every record, keyset paging, conditional GET, Scotland and per-medicine endpoints

  • Every record on /api/v1/shortages, /events, /ssps, /scotland and /medicines/{slug} now carries ss_id (a ShortageSignal id: post:<12 hex>, ssp:NNN and scot:msan:YYYY:N are stable; evt:<id> identifies one emitted event and is replaced when versioned re-parsing re-emits it, so cite an event's record_ss_id instead), recorded_at (when the fact entered the record), recorded_at_precision (exact, or no_later_than where only an upper bound is known: events written before this version whose write time was never stored), recorded_route (whether that first capture was first-hand or the Internet Archive's; a post first recovered from the Archive keeps the Archive's time even after a first-hand capture) and a provenance object: capture route (first_hand or internet_archive), captured_at, sha256 of the captured bytes, the captured URL, the exact Internet Archive capture URL where recovered, parser version and the parser's anomaly notes, verbatim. The existing id and event_key are unchanged; ss_id is additive, never a replacement.
  • /api/v1/events?since_id=evt:0 — keyset paging on the event id. Ids are assigned in recording order, so an event that enters the record late (an Internet-Archive recovery with an old event_date) is delivered after your cursor, never behind it; follow meta.next.since_id until it is null. This is the integration path; webhooks are not offered. The v1.0 cursor (since + after_key) keeps working unchanged.
  • /api/v1/events?as_of=YYYY-MM-DD — only events recorded on or before that UTC date, i.e. the record as it stood then. It is only as complete as capture was by that date, and an event whose recorded time is only an upper bound is left out of dates before that bound; meta.coverage_note says so.
  • Every v1 response, JSON, CSV and XLSX, carries Cache-Control (max-age=0, s-maxage=300, stale-while-revalidate=3600) and an ETag. Send If-None-Match and an unchanged representation returns 304 with no body. The CDN cache window fell from 30 to 5 minutes, and max-age=0 tells browsers and other private caches to revalidate rather than guess a lifetime.
  • The envelope's meta gains schema_version, changelog, license, attribution and coverage_note.
  • New: /api/v1/scotland and /api/v1/export/scotland.csv — NHS Scotland Medicine Supply Alert Notices with the products each notice lists, on a separate surface that is never added to England counts.
  • New: /api/v1/medicines/{slug} — one medicine as the site groups it: its England notices (each with reference, tier, stated expected-back text, ss_id, recorded_at and provenance) and Scotland's notices for the same name, listed separately.
  • Fair-use brake: 60 requests a minute per client IP, per function instance (not a global quota), on /api/v1/* and /api/subscribe; over it, 429 with Retry-After. Pages, feeds and the OpenAPI document are not limited.
  • Notice records gain ref_id (the printed reference as an id, e.g. msn:2026:044; null when the post printed none) and detail_url. SSP records gain register_seen_at.
  • /api/openapi.json is regenerated for 1.1.0; its event_type enum is checked in CI against the database's own constraint.

v1.0 2026-07-14

Launch

  • /api/v1/shortages, /api/v1/events?since= (later with the after_key cursor) and /api/v1/ssps, keyless under fair use, one envelope, a source_url on every record whose source publishes a document.
  • CSV exports of the register and the complete change feed, and the whole record as one formatted workbook.