API Reference

Stable, public endpoints under /api/v1. Hosted at https://www.allnutrition.info. A free API key is required (Authorization: Bearer ank_…, created under Settings → API keys); every account gets the same daily allowance — see Rate limits.

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.
`deep_research`	boolean (default `false`)	Optional. Run the deep-research pipeline: the question is expanded into multiple targeted sub-queries and the answer is a comprehensive, sectioned research report. Slower (typically 30–90 s).
`share`	boolean (default `false`)	Optional. Persist the question and answer as a public, read-only Ask session and return its URL in `share_url`.
`save_session`	boolean (default `true`)	Optional. Save the question and answer to your Ask history in the app (badged as an API/MCP session). Set `false` to skip.

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.
`deep_research`	boolean	Whether the answer was produced by the deep-research pipeline.
`share_url`	string / null	Public URL of the shared Ask session. Only present when the request set `share: true`.
`session_id`	string / null	ID of the Ask session saved to your in-app history. Absent when the request set `save_session: false`.
`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?"}'

Deep research

Set "deep_research": true to trade latency for depth. Instead of a single retrieval pass, the pipeline expands your question into 3–8 targeted sub-queries (e.g. safety, efficacy, mechanisms), retrieves and merges sources for each, and synthesizes a comprehensive Markdown report with inline citations and a summary section. Expect responses in 30–90 seconds and a much longer answer. A deep-research call counts as one request against the rate limit.

Set "share": true to persist the question and answer as a public, read-only Ask session. The response's share_url points to a web page (https://www.allnutrition.info/shared/<slug>) showing the question, the answer, and its citations — useful for handing users a permanent, human-readable link from a chatbot or agent. Notes:

Anyone with the link can view the session; the slug is unguessable but the page is not access-controlled.
Sharing cannot be revoked through the public API — contact support@allnutrition.info to remove a link.
Don't enable share for questions containing personal or sensitive information.
Composable with deep_research — the shared page then shows the full report.

curl -X POST https://www.allnutrition.info/api/v1/ask \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What does the evidence say about intermittent fasting?",
    "deep_research": true,
    "share": true
  }'
# → { ..., "deep_research": true,
#     "share_url": "https://www.allnutrition.info/shared/Ab3dEf9hIj2kLm5n" }

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.

API Reference

Endpoints at a glance

POST /api/v1/ask

Request body

Response (200)

Example

Deep research

Shareable Ask sessions

POST /api/v1/references/search

Request body

Response (200)

Source object

Errors

Interactive explorer