API Reference
Stable, public, no-auth endpoints under /api/v1. Hosted at
https://www.allnutrition.info.
Endpoints at a glance
| Method | Path | Description |
|---|
POST |
/api/v1/ask |
Answer a nutrition question with citations. |
POST |
/api/v1/references/search |
Semantic search of the curated reference library (no LLM). |
GET |
/api/v1/health |
Liveness probe. |
GET |
/openapi.json |
Machine-readable OpenAPI 3.1 specification. |
POST /api/v1/ask
Answer a nutrition question with peer-reviewed citations.
Request body
| Field | Type | Description |
|---|
question | string (1–1000) | Required. The question, in plain English. |
published_after | ISO-8601 datetime | Optional. Only consider sources published on or after this date. |
Response (200)
| Field | Type | Description |
|---|
question | string | Echo of the original question. |
answer | string (Markdown) | Evidence-grounded answer. |
evidence_strength | strong | moderate | limited | insufficient | Strength of the underlying evidence. |
consensus_level | high | moderate | mixed | low | How well the cited sources agree. |
last_updated | ISO-8601 / null | Most recent publication among cited sources. |
sources[] | array | Citations (see Source object). |
Example
curl -X POST https://www.allnutrition.info/api/v1/ask \
-H "Content-Type: application/json" \
-d '{"question": "Is creatine safe for adolescents who lift weights?"}'
POST /api/v1/references/search
Return ranked sources for a query without generating an answer.
Request body
| Field | Type | Description |
|---|
query | string (1–1000) | Required. Free-text query. |
max_results | integer (1–20, default 10) | Maximum sources to return. |
published_after | ISO-8601 / null | Optional cutoff. |
Response (200)
| Field | Type | Description |
|---|
query | string | Echo of the query. |
count | integer | Number of results returned. |
results[] | array | Sources (see Source object), ranked by relevance × trust. |
Source object
Both endpoints return sources with the same shape.
| Field | Type | Description |
|---|
id | string (UUID) | Stable AllNutrition reference ID. |
title | string | Title of the paper, guideline, or article. |
url | string / null | Canonical URL (DOI, journal page, guideline URL). |
publisher | string | Issuing journal, organisation, or guideline body. |
publisher_short_name | string / null | Short identifier (e.g. WHO, AHA, NICE). |
evidence_level | enum | guideline | systematic_review | rct | observational | expert_opinion | review |
trust_score | float [0, 1] | Composite trust: authority × recency × evidence × consensus. |
published_at | ISO-8601 / null | Publication date. |
excerpt | string | Verbatim chunk used as RAG context. |
passage | string / null | Short human-readable preview where available. |
Errors
| Status | Meaning |
|---|
400 | Invalid payload (e.g. empty question, query too long). |
429 | Rate limit exceeded — see Rate limits & errors. |
500 | Unexpected server error. Safe to retry with backoff. |
503 | Upstream model temporarily unavailable. |
Interactive explorer
Try requests live against the API in the
interactive Scalar explorer →
The interactive explorer is rendered from the same OpenAPI spec served at
/openapi.json. You can
download the spec and use it with Postman, Insomnia, Stoplight, or any OpenAPI-compatible tool.