◆ Public API

Vital Pulse API

Public-read endpoints serving the current reading, historical timeseries, methodology document, panel composition, evidence ticker and annual flagship report. CORS is permissive (*); responses include X-Source and X-Methodology-Version headers; cache windows match the publishing cadence.

Full OpenAPI 3.0.3 specification: /vital-pulse/assets/api-endpoints-spec.yaml.

Endpoints

GET /api/vital-pulse/current

Most recent published reading, composite + six pillars with score, status, velocity and direction.

Cache: 1 hour at edge.

Try it: /api/vital-pulse/current

GET /api/vital-pulse/timeseries

Historical readings.

indicator=vp (default) for composite, or one of the pillar IDs (soil-health-trajectory, crop-nutrient-density, polyphenol-bioactive-trend, public-procurement-quality, diet-related-disease-burden, policy-market-momentum).
from=2026-05, to=2027-12 bound the window (inclusive). Year-month format.
include=score|velocity|both (default both).

Cache: 6 hours.

GET /api/vital-pulse/methodology

Current methodology version with weights, velocity-window length, direction thresholds, sources and panel approval state. Specific historical versions: /api/vital-pulse/methodology/{version}.

Cache: 24 hours (current); 30 days (specific version, immutable).

GET /api/vital-pulse/panel

Methodology panel composition. Empty in Phase 0; populated when the panel is seated in Phase 1.

GET /api/vital-pulse/ticker

Live evidence ticker — last 50 events from the Pulse Brain ingest pipeline.

Cache: 30 minutes, with 10 minutes stale-while-revalidate.

GET /api/vital-pulse/annual/{year}

Annual flagship report payload for the given year. Phase 0 returns a placeholder shell.

Embed widget

A self-contained HTML embed of the headline gauge, suitable for partner sites and media embeds. Inline CSS + SVG, no external dependencies, accessible.

Composite-only (≤ 50KB):

<iframe src="https://vitagri.org/api/vital-pulse/embed/headline"
        width="420" height="360" frameborder="0"
        title="UK Food System Vital Pulse"></iframe>

Full (composite + six pillar gauges, ≤ 120KB):

<iframe src="https://vitagri.org/api/vital-pulse/embed/headline?variant=full"
        width="720" height="640" frameborder="0"
        title="UK Food System Vital Pulse — full"></iframe>

Optional ?theme=dark for inverted colours. Both variants carry a visible "Source: Vitagri Vital Pulse Index, methodology v{x}" footer line and, where applicable, "Source: Bionutrient Institute".

Headers

X-Source: comma-separated list of source organisations whose data contributed to the response. Always includes "Vitagri Vital Pulse Index"; includes "Bionutrient Institute" for BI-attributed readings.
X-Methodology-Version: methodology version active when the response was generated. Lets cached responses be invalidated correctly when methodology bumps.
Cache-Control: tuned per-endpoint to the publishing cadence.

Rate limits

Public-read endpoints are protected by Netlify edge rate limiting only. No per-key throttling at this stage; if aggressive consumption emerges, a fair-use policy lands here and a soft API-key gate is introduced. No keys required in Phase 0.

Admin endpoints

Write endpoints under /api/vital-pulse/admin/ (draft, publish, panel updates, methodology versioning, ticker refresh) require an admin session and, for publish, a panel-chair authorisation token. Documented in the OpenAPI spec linked above; not part of the public surface.