How much does it cost?

Anonymous use is free at 100 requests per minute per IP. A free Researcher key gives you 1,000 requests per minute for research, journalism, education, and prototypes. The Commercial tier offers 5,000 requests per minute plus an SLA for commercial redistribution.

Do I need an API key?

No. Anonymous calls work at 100 requests per minute per IP. A free Researcher key unlocks 1,000 requests per minute; pass it in the X-API-Key header.

What endpoint actions are available?

Four actions on a single endpoint: list (paginated, filterable list), get (single record plus related items), count (total visible records), and facets (all facet values with counts).

What filters does the API support?

Full-text q search, subjectTheme, theme, geography, sourceType, publicationStatus, studyType, tier (1–4), year, sort (relevance/recent/year/tier/title), pagination (page/pageSize, max 100), and scoring (hybrid/semantic/lexical). Filters combine freely with AND logic.

What's the difference between /api/v1/evidence and /api/evidence?

/api/v1/evidence is the recommended version-pinned path — it will only change via backwards-compatible additions. /api/evidence is the rolling latest-stable alias; it currently tracks v1 but will move forward under future major versions.

Can I use the data commercially?

Yes — for commercial products, redistribution, or higher rate limits, request a Commercial key via info@vitagri.org. Catalogue metadata may be reused but original sources remain under their own copyright — please cite the underlying publisher alongside the Pulse Brain.

Pulse Brain Evidence API

Q: What is the Pulse Brain Evidence API?

A public read-only API providing hybrid semantic search over ~4,000 curated research records covering nutrition, soil health, regenerative agriculture, and food systems. OpenAPI 3.1 with three tiers — Free (anonymous), Researcher (free key), and Commercial (admin-issued with an SLA).

Read-only public access to Vitagri's curated catalogue of ~4,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.