Pulse Brain Evidence API

Read-only public access to Vitagri's curated catalogue of 19,000+ records on nutrition, soil health, regenerative agriculture, and food systems. Three tiers — anonymous works for casual use, a free Researcher key gives you 10× the throughput, and Commercial is admin-issued with an SLA.

Try it live — no key, no setup

Run real queries against the catalogue right now. Pre-built scenarios for hybrid semantic search, faceting, single-record fetch, and more — with live request previews and rate-limit headers.

Open the live demo → Get a free Researcher key

Access tiers

Tier	Limit	Use	How to get one
Free	100 / min, per IP	Casual / personal	No key needed — just call the API
Researcher	1,000 / min, per key	Research, journalism, education, prototypes	Sign up — free
Commercial	5,000 / min, per key + SLA	Commercial products, redistribution, high volume	Email info@vitagri.org

Pass your key in the X-API-Key header. When you exceed the limit you'll get a 429 with a Retry-After header.

v1 · stable OpenAPI 3.1

Specification

Full machine-readable schema covering every endpoint, parameter, and response shape:

openapi.yaml /api/v1/openapi.yaml

Base URLs

The versioned alias is the recommended integration path; the unversioned function path is the rolling-latest equivalent and may move under future versions.

https://www.vitagri.org/api/v1/evidence — recommended, version-pinned
https://www.vitagri.org/api/evidence — rolling latest (currently v1)
https://www.vitagri.org/.netlify/functions/evidence — direct function, also rolling latest

Actions

The single endpoint multiplexes by the action query parameter:

listPaginated, filterable list of records. Default when action is omitted.
getSingle record by id, plus up to six related records.
countTotal visible record count for the catalogue.
facetsAll facet values + counts across the visible catalogue.

Quick examples

1. Top regenerative-agriculture papers from 2024

curl "https://www.vitagri.org/api/v1/evidence?subjectTheme=Regenerative%20agriculture&year=2024&sort=tier&pageSize=10"

2. Hybrid semantic search

curl "https://www.vitagri.org/api/v1/evidence?q=phytonutrient+density&scoring=hybrid"

3. All current facet values

curl "https://www.vitagri.org/api/v1/evidence?action=facets"

4. Single record with related items

curl "https://www.vitagri.org/api/v1/evidence?action=get&id=PB12345"

Filtering

All filter parameters can be combined freely:

q — full-text search (≥ 2 characters)
theme, subjectTheme — canonical theme/subject enums
geography — canonical country/region
sourceType — Peer-reviewed research, Preprint, Industry/policy report, Grey literature, …
publicationStatus — Published, Preprint, Under review
studyType — RCT, Systematic review, Cohort study, …
tier — 1 to 4, where 1 is highest-confidence
year — publication year (integer)
sort — relevance, recent, year, tier, title
page, pageSize — pagination (max 100 per page)
scoring — hybrid, semantic, lexical (only effective with q)

Versioning policy

v1 is the current public contract. Changes to v1 will be backwards-compatible additions only — new optional parameters, new response fields, new facet keys. Any breaking change opens a new /api/v2/... path; v1 will continue to resolve for at least 12 months after a v2 ships.

The unversioned /api/evidence path always tracks the latest stable version.

Licence and attribution

Catalogue metadata may be reused for research, journalism, and product integration. Original sources remain under their own copyright — please cite the underlying publisher as well as the Pulse Brain when republishing. For commercial redistribution, bulk export, or higher rate limits, contact info@vitagri.org.

How the Pulse Brain was created, and how its citations are managed and maintained, is confidential to Vitagri and is not documented here or answered by the API. If you have a question about it, contact Rob Ward at rob.ward@vitagri.org, who will be glad to help.