{"openapi":"3.1.0","info":{"title":"AllNutrition API","summary":"Evidence-based nutrition guidance with citations to peer-reviewed research.","description":"**AllNutrition** is an evidence-based nutrition API. Every answer is grounded in\npeer-reviewed research, clinical guidelines, and expert position statements\ncurated by AllNutrition, and includes citations to the underlying sources.\n\n### What this API is good for\n\n- **AI agents and tools** that need cited, evidence-tier-labelled nutrition guidance\n- **Custom assistants and chatbots** that want to ground responses in real research\n- **Apps and integrations** that need a programmatic interface to AllNutrition\n\n### Stable, public surface — `/api/v1/*`\n\nThe `/api/v1/*` endpoints are the **public, no-auth, rate-limited** surface\ndesigned for external developers and AI agents.\n\n- `POST /api/v1/ask` — full RAG answer + citations\n- `POST /api/v1/references/search` — semantic reference search, no LLM call\n\nEvery response carries `evidence_strength` (`strong | moderate | limited | insufficient`)\nand `consensus_level` (`high | moderate | mixed | low`) so calling agents can\ndecide how confidently to use the answer.\n\n### Rate limits\n\nThe public API is rate-limited to **10 requests per IP per UTC day**. All\nresponses include `RateLimit-*` headers so honest clients can self-throttle.\n\n### Documentation\n\nFull developer documentation, integration recipes (OpenAI tool use, Claude tool use,\nGPT Actions, LangChain, etc.), and conceptual explainers live at\n**[docs.allnutrition.info](https://docs.allnutrition.info)**.\n\nThe machine-readable OpenAPI 3.1 spec is available at\n[`/openapi.json`](https://www.allnutrition.info/openapi.json).\n","contact":{"name":"AllNutrition Support","url":"https://docs.allnutrition.info/","email":"support@allnutrition.info"},"license":{"name":"Terms of Service","url":"https://www.allnutrition.info/terms"},"version":"1.0.0","x-logo":{"url":"https://www.allnutrition.info/favicon.png","altText":"AllNutrition"}},"servers":[{"url":"https://www.allnutrition.info","description":"Production"}],"paths":{"/api/v1/ask":{"post":{"tags":["public"],"summary":"Ask an evidence-based nutrition question","description":"Answer a nutrition question using AllNutrition's curated library of peer-reviewed research, clinical guidelines, and expert position statements. Every answer includes citations to retrievable sources, an `evidence_strength` label, and a `consensus_level` label so calling agents can decide how confidently to use the answer.\n\n**Best for:** RAG agents, GPT Actions, custom assistants that need cited nutrition guidance.\n\n**Rate limit:** 10 requests per IP per UTC day.","operationId":"askNutritionQuestion","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":10,"title":"Limit"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAskRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAskResponse"}}}},"400":{"description":"Invalid request payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded. Public API allows 10 requests per IP per UTC day. Response includes `Retry-After` and `RateLimit-*` headers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Upstream model temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/references/search":{"post":{"tags":["public"],"summary":"Search the curated reference library","description":"Retrieve a ranked list of peer-reviewed sources for a query, **without** generating an LLM answer. Use this when you want to feed citations into your own pipeline, build a custom answer, or surface evidence directly in a UI.\n\nResults are ranked by semantic similarity × composite trust score and deduplicated to one entry per source.\n\n**Rate limit:** 10 requests per IP per UTC day (shared with `/v1/ask`).","operationId":"searchReferences","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":10,"title":"Limit"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferencesSearchRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferencesSearchResponse"}}}},"400":{"description":"Invalid request payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded. Public API allows 10 requests per IP per UTC day. Response includes `Retry-After` and `RateLimit-*` headers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Upstream model temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/health":{"get":{"tags":["public"],"summary":"Public API health probe","description":"Lightweight liveness check. Not rate limited.","operationId":"publicHealth","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Publichealth"}}}}}}},"/api/auth/me":{"get":{"tags":["auth"],"summary":"Get Me","operationId":"get_me_api_auth_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/auth/logout":{"post":{"tags":["auth"],"summary":"Logout","operationId":"logout_api_auth_logout_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/users/me":{"patch":{"tags":["users"],"summary":"Patch Me","description":"Shallow-merge partial updates into the user record.","operationId":"patch_me_api_users_me_patch","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartialUserUpdate"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/users/profile":{"get":{"tags":["users"],"summary":"Get Profile","operationId":"get_profile_api_users_profile_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResponse"}}}}},"security":[{"HTTPBearer":[]}]},"put":{"tags":["users"],"summary":"Update Profile","operationId":"update_profile_api_users_profile_put","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserProfileUpdate"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/users/account":{"delete":{"tags":["users"],"summary":"Delete Account","operationId":"delete_account_api_users_account_delete","responses":{"204":{"description":"Successful Response"}},"security":[{"HTTPBearer":[]}]}},"/api/newsletter/subscribe":{"post":{"tags":["newsletter"],"summary":"Subscribe","operationId":"subscribe_api_newsletter_subscribe_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewsletterSubscribeRequest"}}},"required":true},"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/newsletter/unsubscribe":{"get":{"tags":["newsletter"],"summary":"Unsubscribe","operationId":"unsubscribe_api_newsletter_unsubscribe_get","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","description":"Email address to remove","title":"Email"},"description":"Email address to remove"}],"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/ask":{"post":{"tags":["ask"],"summary":"Ask","operationId":"ask_api_ask_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AskRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AskResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/ask/external":{"post":{"tags":["ask-external"],"summary":"Ask External","operationId":"ask_external_api_ask_external_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AskRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AskResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/chats":{"get":{"tags":["chats"],"summary":"List Chats","description":"Return all chats for the current user (title + id only, newest first).","operationId":"list_chats_api_chats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/ChatListItem"},"type":"array","title":"Response List Chats Api Chats Get"}}}}},"security":[{"HTTPBearer":[]}]},"post":{"tags":["chats"],"summary":"Create Chat","description":"Create a new empty chat session.","operationId":"create_chat_api_chats_post","responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatDetail"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/chats/{chat_id}":{"get":{"tags":["chats"],"summary":"Get Chat","operationId":"get_chat_api_chats__chat_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"chat_id","in":"path","required":true,"schema":{"type":"string","title":"Chat Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["chats"],"summary":"Delete Chat","operationId":"delete_chat_api_chats__chat_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"chat_id","in":"path","required":true,"schema":{"type":"string","title":"Chat Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["chats"],"summary":"Update Chat Title","operationId":"update_chat_title_api_chats__chat_id__patch","security":[{"HTTPBearer":[]}],"parameters":[{"name":"chat_id","in":"path","required":true,"schema":{"type":"string","title":"Chat Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateChatTitleRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatListItem"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/chats/{chat_id}/preview-prompt":{"post":{"tags":["chats"],"summary":"Preview Prompt","description":"Run retrieval + prompt construction and return the final prompt without calling the LLM.\n\nThe returned preview_token can be passed to the send-message endpoint so it\nskips retrieval and goes straight to the model — faster first token.","operationId":"preview_prompt_api_chats__chat_id__preview_prompt_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"chat_id","in":"path","required":true,"schema":{"type":"string","title":"Chat Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewPromptResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/chats/{chat_id}/messages":{"post":{"tags":["chats"],"summary":"Send Message","operationId":"send_message_api_chats__chat_id__messages_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"chat_id","in":"path","required":true,"schema":{"type":"string","title":"Chat Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/chats/{chat_id}/fork":{"post":{"tags":["chats"],"summary":"Fork Chat","description":"Create a full copy of a chat (backup before editing).","operationId":"fork_chat_api_chats__chat_id__fork_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"chat_id","in":"path","required":true,"schema":{"type":"string","title":"Chat Id"}}],"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/chats/{chat_id}/share":{"post":{"tags":["chats"],"summary":"Share Chat","description":"Mark a chat as public and return its share slug.\n\nIf the chat is already public, returns the existing slug (idempotent).\nRefuses to share if any user message contains injected personal/family\ncontext — the assistant's answers in that case reference the personal\ninfo inline and can't be safely sanitized.","operationId":"share_chat_api_chats__chat_id__share_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"chat_id","in":"path","required":true,"schema":{"type":"string","title":"Chat Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareChatResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["chats"],"summary":"Unshare Chat","description":"Revoke public sharing on a chat. Existing links return 404.","operationId":"unshare_chat_api_chats__chat_id__share_delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"chat_id","in":"path","required":true,"schema":{"type":"string","title":"Chat Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareChatResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/chats/{chat_id}/messages/{message_id}":{"put":{"tags":["chats"],"summary":"Edit Message","description":"Replace a user message's content, delete everything after it, and re-run RAG.","operationId":"edit_message_api_chats__chat_id__messages__message_id__put","security":[{"HTTPBearer":[]}],"parameters":[{"name":"chat_id","in":"path","required":true,"schema":{"type":"string","title":"Chat Id"}},{"name":"message_id","in":"path","required":true,"schema":{"type":"string","title":"Message Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditMessageRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/chats/public/{slug}":{"get":{"tags":["chats"],"summary":"Get Public Chat","description":"Anyone can read a shared chat by slug. No auth required.\n\nStrips per-user fields and the embedded final_prompt (which would leak\nfamily/member context the owner injected when sending).","operationId":"get_public_chat_api_chats_public__slug__get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicChatDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/references/groups":{"get":{"tags":["references"],"summary":"List Reference Groups","operationId":"list_reference_groups_api_references_groups_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/ReferenceGroupResponse"},"type":"array","title":"Response List Reference Groups Api References Groups Get"}}}}},"security":[{"HTTPBearer":[]}]},"post":{"tags":["references"],"summary":"Create Reference Group","operationId":"create_reference_group_api_references_groups_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferenceGroupCreate"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferenceGroupResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/references/submit":{"post":{"tags":["references"],"summary":"Submit Reference","description":"Submit a new reference source through the full ingestion pipeline:\n\n1. Trust score check — rejects sources that are too old (>30 years by default),\n   have very low journal impact factor, or score below the minimum composite\n   trust threshold.\n\n2. Conflict-of-interest check — an LLM subagent evaluates the source for\n   industry funding and financial interest signals. If COI is detected with\n   sufficient confidence the source is saved as **coi_flagged** and a 409 is\n   returned. A human reviewer must then call POST /{id}/bypass-coi to approve it.\n\n3. Content summarisation — an LLM extracts the main research question,\n   methodology, key findings, and conclusions (skipping intro/background).\n\n4. Embedding — the summary (not the raw text) is chunked and embedded for\n   RAG retrieval so the vector space reflects actual scientific content.\n\nReturns 201 on success, 409 on COI flag, 422 on trust rejection.","operationId":"submit_reference_api_references_submit_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferenceSubmit"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferenceSubmitResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/references/{ref_id}/bypass-coi":{"post":{"tags":["references"],"summary":"Bypass Coi Flag","description":"Human-approved bypass of a COI-flagged source.\n\nAfter this call the source is summarised (if not already), embedded, and\nset to status 'coi_bypassed' — making it available for RAG and test generation.\n\nA non-empty reason is required to create an audit trail.","operationId":"bypass_coi_flag_api_references__ref_id__bypass_coi_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"ref_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Ref Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/COIBypassRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/references/facets":{"get":{"tags":["references"],"summary":"Get Facets","description":"Return contextual facet counts for the Sources filter panel.\n\nAccepts the same filter params as /search. Each facet dimension is counted\nwith all OTHER active filters applied, so the numbers show how many results\neach additional option would yield given the current selection.","operationId":"get_facets_api_references_facets_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"article_primary","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Article Primary"}},{"name":"evidence_levels","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Evidence Levels"}},{"name":"human_only","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Human Only"}},{"name":"year_from","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Year From"}},{"name":"year_to","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Year To"}},{"name":"sample_size_brackets","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Sample Size Brackets"}},{"name":"duration_categories","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Duration Categories"}},{"name":"population_groups","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Population Groups"}},{"name":"reference_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reference Type"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/references/search":{"get":{"tags":["references"],"summary":"Search References","description":"List active references matching the given facet filters.\n\nReturns { total: int, results: Reference[] } where total is the count of\nmatching references (ignoring pagination) so the UI can show \"123 results\".\nAll filter params are optional; omitting them returns all active references.\nEach result includes a per-user ``test_requested`` boolean.","operationId":"search_references_api_references_search_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"article_primary","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Article Primary"}},{"name":"evidence_levels","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Evidence Levels"}},{"name":"human_only","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Human Only"}},{"name":"year_from","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Year From"}},{"name":"year_to","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Year To"}},{"name":"sample_size_brackets","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Sample Size Brackets"}},{"name":"duration_categories","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Duration Categories"}},{"name":"population_groups","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Population Groups"}},{"name":"reference_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reference Type"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":40,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/references/vector-search":{"post":{"tags":["references"],"summary":"Vector Search References","description":"Semantic vector search using the same scoring pipeline as Ask.\n\nEmbeds the query, retrieves the closest chunks via pgvector, reranks by\ntrust score, deduplicates to one result per reference, then fetches full\nReference records so the frontend can render them with ReferenceCard.\n\nReturns { results: Reference[] } where each item has extra\n``similarity`` and ``final_score`` fields for relevance display.\nLimit is capped at 30; threshold filtering follows the Ask pipeline.","operationId":"vector_search_references_api_references_vector_search_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VectorSearchRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/references":{"get":{"tags":["references"],"summary":"List References","description":"List references. Filter by group_id and/or source_status.\n\nUseful status values: approved, coi_bypassed, coi_flagged, low_trust_rejected","operationId":"list_references_api_references_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"group_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Group Id"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ReferenceResponse"},"title":"Response List References Api References Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["references"],"summary":"Create Reference","description":"Direct DB insert — bypasses trust/COI checks and summarisation.\nIntended for seeding scripts and internal tooling only.\nUse POST /api/references/submit for normal source submission.","operationId":"create_reference_api_references_post","security":[{"HTTPBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferenceCreate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferenceResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/references/{ref_id}":{"get":{"tags":["references"],"summary":"Get Reference","operationId":"get_reference_api_references__ref_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"ref_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Ref Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferenceResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/references/{ref_id}/feedback":{"post":{"tags":["references"],"summary":"Submit Reference Feedback","description":"Submit a flag or feedback report on a reference.\n\nfeedback_type options:\n- conflict_of_interest\n- inaccurate_information\n- incorrect_category\n- other (requires feedback_text)","operationId":"submit_reference_feedback_api_references__ref_id__feedback_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"ref_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Ref Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackSubmit"}}}},"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/references/{ref_id}/request-test":{"post":{"tags":["references"],"summary":"Request Reference Test","description":"Request that a knowledge test be created for a reference.\n\nOnly meaningful when the reference has no tests yet (test_count = 0).\nDuplicate requests from the same user on the same reference are allowed\n(each one counts as a signal of demand).","operationId":"request_reference_test_api_references__ref_id__request_test_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"ref_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Ref Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/references/{ref_id}/embed":{"post":{"tags":["references"],"summary":"Embed Reference","description":"Re-generate embeddings for a reference from its content_summary.","operationId":"embed_reference_api_references__ref_id__embed_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"ref_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Ref Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/tests":{"get":{"tags":["tests"],"summary":"List Tests","description":"Return all tests with the current user's most-recent attempt data joined in\nvia a LATERAL subquery so completed tests are distinguishable.\n\nAlso resolves a human-readable source_name from reference_groups by matching\nsource_refs URLs against the references table.","operationId":"list_tests_api_tests_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"difficulty","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Difficulty"}},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"}},{"name":"source_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Name"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/tests/{test_id}":{"get":{"tags":["tests"],"summary":"Get Test","operationId":"get_test_api_tests__test_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"test_id","in":"path","required":true,"schema":{"type":"string","title":"Test Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/tests/{test_id}/submit":{"post":{"tags":["tests"],"summary":"Submit Test","operationId":"submit_test_api_tests__test_id__submit_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"test_id","in":"path","required":true,"schema":{"type":"string","title":"Test Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Payload"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/transcribe":{"post":{"tags":["transcribe"],"summary":"Transcribe Audio","description":"Proxy audio to Deepgram and return the transcript. Keeps the API key server-side.","operationId":"transcribe_audio_api_transcribe_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_transcribe_audio_api_transcribe_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}}},"components":{"schemas":{"AskRequest":{"properties":{"query":{"type":"string","title":"Query"},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location"},"filters":{"anyOf":[{"$ref":"#/components/schemas/ReferenceFilters"},{"type":"null"}]},"published_after":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Published After"},"model":{"type":"string","title":"Model","default":"auto"}},"type":"object","required":["query"],"title":"AskRequest"},"AskResponse":{"properties":{"answer":{"type":"string","title":"Answer"},"sources":{"items":{"$ref":"#/components/schemas/SourceResponse"},"type":"array","title":"Sources"},"evidence_strength":{"type":"string","title":"Evidence Strength"},"consensus_level":{"type":"string","title":"Consensus Level"},"last_updated":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Updated"},"query_log_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query Log Id"},"model_notice":{"anyOf":[{"$ref":"#/components/schemas/ModelNotice"},{"type":"null"}]}},"type":"object","required":["answer","sources","evidence_strength","consensus_level"],"title":"AskResponse"},"Body_transcribe_audio_api_transcribe_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"}},"type":"object","required":["file"],"title":"Body_transcribe_audio_api_transcribe_post"},"COIBypassRequest":{"properties":{"reason":{"type":"string","title":"Reason"}},"type":"object","required":["reason"],"title":"COIBypassRequest","description":"Human-approved bypass of a COI-flagged source."},"ChatDetail":{"properties":{"id":{"type":"string","title":"Id"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"messages":{"items":{"$ref":"#/components/schemas/ChatMessageResponse"},"type":"array","title":"Messages"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"is_public":{"type":"boolean","title":"Is Public","default":false},"public_slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Public Slug"}},"type":"object","required":["id","messages","created_at","updated_at"],"title":"ChatDetail"},"ChatListItem":{"properties":{"id":{"type":"string","title":"Id"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"is_public":{"type":"boolean","title":"Is Public","default":false},"public_slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Public Slug"}},"type":"object","required":["id","created_at","updated_at"],"title":"ChatListItem"},"ChatMessageResponse":{"properties":{"id":{"type":"string","title":"Id"},"role":{"type":"string","title":"Role"},"content":{"type":"string","title":"Content"},"sources":{"anyOf":[{"items":{"$ref":"#/components/schemas/SourceResponse"},"type":"array"},{"type":"null"}],"title":"Sources"},"evidence_strength":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Evidence Strength"},"consensus_level":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Consensus Level"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"final_prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Final Prompt"}},"type":"object","required":["id","role","content","created_at"],"title":"ChatMessageResponse"},"EditMessageRequest":{"properties":{"content":{"type":"string","title":"Content"},"filters":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Filters"},"preview_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Preview Token"}},"type":"object","required":["content"],"title":"EditMessageRequest"},"ErrorResponse":{"properties":{"detail":{"type":"string","title":"Detail","description":"Human-readable error message."}},"type":"object","required":["detail"],"title":"ErrorResponse","description":"Generic error envelope."},"FamilyMember":{"properties":{"id":{"type":"string","title":"Id"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label"},"dob_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Dob Year"},"dob_month":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Dob Month"},"dob_day":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Dob Day"},"gender":{"anyOf":[{"type":"string","enum":["Male","Female"]},{"type":"null"}],"title":"Gender"},"dietary_prefs":{"items":{"type":"string"},"type":"array","title":"Dietary Prefs","default":[]},"health_conditions":{"items":{"type":"string"},"type":"array","title":"Health Conditions","default":[]}},"type":"object","required":["id"],"title":"FamilyMember"},"FeedbackSubmit":{"properties":{"feedback_type":{"type":"string","title":"Feedback Type"},"feedback_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Feedback Text"}},"type":"object","required":["feedback_type"],"title":"FeedbackSubmit","description":"User-submitted flag on a reference card."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ModelNotice":{"properties":{"provider":{"type":"string","title":"Provider"},"quota_resets_at":{"type":"string","format":"date-time","title":"Quota Resets At"}},"type":"object","required":["provider","quota_resets_at"],"title":"ModelNotice","description":"Sent when the response was served by a fallback model so the UI can\nexplain to the user why and when the primary model will be available again."},"NewsletterSubscribeRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email"}},"type":"object","required":["email"],"title":"NewsletterSubscribeRequest"},"PartialUserUpdate":{"properties":{"preferences":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Preferences"}},"type":"object","title":"PartialUserUpdate"},"PreviewPromptResponse":{"properties":{"final_prompt":{"type":"string","title":"Final Prompt"},"preview_token":{"type":"string","title":"Preview Token"}},"type":"object","required":["final_prompt","preview_token"],"title":"PreviewPromptResponse"},"PublicAskRequest":{"properties":{"question":{"type":"string","maxLength":1000,"minLength":1,"title":"Question","description":"The nutrition question, in plain English. Max 1000 characters.","examples":["How much vitamin D should an adult take daily?"]},"published_after":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Published After","description":"Optional ISO-8601 cutoff — only consider sources published on or after this date. Use to bias toward recent evidence.","examples":["2020-01-01T00:00:00Z"]}},"type":"object","required":["question"],"title":"PublicAskRequest","description":"A nutrition question to be answered with citations from peer-reviewed research.","examples":[{"question":"How much vitamin D should an adult take daily?"},{"published_after":"2018-01-01T00:00:00Z","question":"Is creatine safe for adolescents who lift weights?"}]},"PublicAskResponse":{"properties":{"question":{"type":"string","title":"Question","description":"Echo of the original question."},"answer":{"type":"string","title":"Answer","description":"Markdown-formatted answer grounded in the cited sources. Includes specific numbers/dosages where the evidence supports them."},"evidence_strength":{"type":"string","enum":["strong","moderate","limited","insufficient"],"title":"Evidence Strength","description":"Overall strength of the evidence backing the answer. `strong` = top-tier sources (guidelines, systematic reviews) with high trust. `moderate` = solid evidence with some gaps. `limited` = sparse or lower-tier evidence; treat as preliminary. `insufficient` = not enough trusted sources to answer; the answer field will explain this and suggest consulting a clinician."},"consensus_level":{"type":"string","enum":["high","moderate","mixed","low"],"title":"Consensus Level","description":"How well the cited sources agree. `high` = sources align. `moderate` = mostly aligned with some variation. `mixed` = notable disagreement. `low` = sources conflict — the answer presents the mainstream view but cites the disagreement."},"last_updated":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Updated","description":"Most recent publication date among the cited sources (ISO-8601)."},"sources":{"items":{"$ref":"#/components/schemas/PublicSource"},"type":"array","title":"Sources","description":"Citations supporting the answer, ordered by relevance."}},"type":"object","required":["question","answer","evidence_strength","consensus_level"],"title":"PublicAskResponse","description":"An evidence-based answer with citations.","examples":[{"answer":"Most adults need **600–800 IU (15–20 mcg) of vitamin D per day** from food, sunlight, or supplements. Adults at higher risk of deficiency (older adults, limited sun exposure, darker skin) may benefit from 1000–2000 IU/day...\n\n*Consult a clinician before starting high-dose supplementation.*","consensus_level":"high","evidence_strength":"strong","last_updated":"2024-03-12T00:00:00Z","question":"How much vitamin D should an adult take daily?","sources":[{"evidence_level":"guideline","excerpt":"The Recommended Dietary Allowance for adults 19–70 years is 600 IU (15 mcg) daily; adults over 70 need 800 IU (20 mcg).","id":"8f4e1c8a-9b6d-4f3e-9a12-0e7d2b6c1a44","published_at":"2024-03-12T00:00:00Z","publisher":"NIH Office of Dietary Supplements","publisher_short_name":"NIH ODS","title":"Vitamin D — Fact Sheet for Health Professionals","trust_score":0.92,"url":"https://ods.od.nih.gov/factsheets/VitaminD-HealthProfessional/"}]}]},"PublicChatDetail":{"properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"messages":{"items":{"$ref":"#/components/schemas/PublicChatMessage"},"type":"array","title":"Messages"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["messages","created_at","updated_at"],"title":"PublicChatDetail","description":"Chat detail returned by the public, no-auth endpoint.\n\nNotably omits ``final_prompt`` (which embeds the owner's family/member\ncontext that was injected before sending to the LLM)."},"PublicChatMessage":{"properties":{"id":{"type":"string","title":"Id"},"role":{"type":"string","title":"Role"},"content":{"type":"string","title":"Content"},"sources":{"anyOf":[{"items":{"$ref":"#/components/schemas/SourceResponse"},"type":"array"},{"type":"null"}],"title":"Sources"},"evidence_strength":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Evidence Strength"},"consensus_level":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Consensus Level"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","role","content","created_at"],"title":"PublicChatMessage","description":"A chat message stripped of per-user fields for public viewing."},"PublicSource":{"properties":{"id":{"type":"string","title":"Id","description":"Stable AllNutrition reference ID (UUID). Use this to cite or fetch the source.","examples":["8f4e1c8a-9b6d-4f3e-9a12-0e7d2b6c1a44"]},"title":{"type":"string","title":"Title","description":"Title of the paper, guideline, or article.","examples":["Vitamin D supplementation and prevention of acute respiratory tract infections"]},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"Canonical URL for the source (DOI, journal page, or guideline URL).","examples":["https://doi.org/10.1136/bmj.i6583"]},"publisher":{"type":"string","title":"Publisher","description":"The organisation, journal, or guideline body that issued the source.","examples":["BMJ","World Health Organization","American Heart Association"]},"publisher_short_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Publisher Short Name","description":"Short identifier for the publisher (e.g. 'WHO', 'AHA', 'NICE').","examples":["WHO"]},"evidence_level":{"type":"string","enum":["guideline","systematic_review","rct","observational","expert_opinion","review"],"title":"Evidence Level","description":"Type of evidence the source provides. One of: `guideline`, `systematic_review`, `rct`, `observational`, `expert_opinion`, `review`. Higher tiers carry more weight.","examples":["systematic_review"]},"trust_score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Trust Score","description":"Composite trust score in [0, 1] combining publisher authority, study design, recency, and consensus. Useful for downstream ranking.","examples":[0.82]},"published_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Published At","description":"Publication date in ISO-8601. May be null when not known.","examples":["2017-02-15T00:00:00Z"]},"excerpt":{"type":"string","title":"Excerpt","description":"Verbatim text chunk from the source used as context for the answer. Suitable for quoting alongside the citation."},"passage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Passage","description":"Short human-readable preview (1–2 sentences) when available."}},"type":"object","required":["id","title","publisher","evidence_level","trust_score","excerpt"],"title":"PublicSource","description":"A single citation backing an answer.\n\nEach source maps to a real, retrievable scientific reference (peer-reviewed\npaper, clinical guideline, or expert position statement). The ``excerpt``\nis the verbatim chunk of text used as RAG context for the answer."},"RateLimitErrorBody":{"properties":{"error":{"type":"string","const":"rate_limit_exceeded","title":"Error"},"message":{"type":"string","title":"Message"},"limit":{"type":"integer","title":"Limit","description":"Daily request limit per IP."},"remaining":{"type":"integer","title":"Remaining"},"reset_at":{"type":"integer","title":"Reset At","description":"Unix timestamp (UTC) when the limit resets."}},"type":"object","required":["error","message","limit","remaining","reset_at"],"title":"RateLimitErrorBody"},"RateLimitErrorResponse":{"properties":{"detail":{"$ref":"#/components/schemas/RateLimitErrorBody"}},"type":"object","required":["detail"],"title":"RateLimitErrorResponse","description":"Returned with HTTP 429 when an IP exceeds its daily limit."},"ReferenceCreate":{"properties":{"ref_group_id":{"type":"string","format":"uuid","title":"Ref Group Id"},"title":{"type":"string","title":"Title"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"content_type":{"type":"string","title":"Content Type","default":"webpage"},"evidence_level":{"type":"string","title":"Evidence Level","default":"review"},"target_populations":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Target Populations"},"topics":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Topics"},"geographic_relevance":{"type":"string","title":"Geographic Relevance","default":"global"},"consensus_score":{"type":"number","title":"Consensus Score","default":0.5},"published_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Published At"}},"type":"object","required":["ref_group_id","title"],"title":"ReferenceCreate","description":"Direct DB insert schema — bypasses the ingestion pipeline.\nUse ReferenceSubmit for normal source submission via the API."},"ReferenceFilters":{"properties":{"article_primary":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Article Primary"},"evidence_levels":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Evidence Levels"},"human_only":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Human Only"},"year_from":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Year From"},"year_to":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Year To"},"sample_size_brackets":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Sample Size Brackets"},"duration_categories":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Duration Categories"},"population_groups":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Population Groups"},"reference_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reference Type"}},"type":"object","title":"ReferenceFilters","description":"Consumer-facing filters that narrow the reference pool before vector search.\n\nDesigned to be intuitive for general users, not researchers.\nPersisted in user.preferences.source_filters so they carry over to Ask and\nchat sessions automatically."},"ReferenceGroupCreate":{"properties":{"name":{"type":"string","title":"Name"},"short_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Short Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"logo_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Logo Url"},"authority_weight":{"type":"number","title":"Authority Weight","default":0.5}},"type":"object","required":["name"],"title":"ReferenceGroupCreate"},"ReferenceGroupResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"short_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Short Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"logo_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Logo Url"},"authority_weight":{"type":"number","title":"Authority Weight"},"is_active":{"type":"boolean","title":"Is Active"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","name","authority_weight","is_active","created_at"],"title":"ReferenceGroupResponse"},"ReferenceResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"ref_group_id":{"type":"string","format":"uuid","title":"Ref Group Id"},"title":{"type":"string","title":"Title"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"content_type":{"type":"string","title":"Content Type"},"evidence_level":{"type":"string","title":"Evidence Level"},"target_populations":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Target Populations"},"topics":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Topics"},"geographic_relevance":{"type":"string","title":"Geographic Relevance"},"consensus_score":{"type":"number","title":"Consensus Score"},"composite_trust_score":{"type":"number","title":"Composite Trust Score"},"source_status":{"type":"string","title":"Source Status"},"coi_bypassed":{"type":"boolean","title":"Coi Bypassed"},"doi":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Doi"},"authors":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Authors"},"journal_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Journal Name"},"impact_factor":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Impact Factor"},"source_specific_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Specific Note"},"content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content Hash"},"source_file_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source File Hash"},"article_primary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Article Primary"},"study_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Study Type"},"n_participants":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"N Participants"},"duration":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Duration"},"test_count":{"type":"integer","title":"Test Count","default":0},"test_requested":{"type":"boolean","title":"Test Requested","default":false},"published_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Published At"},"last_updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Updated At"},"is_active":{"type":"boolean","title":"Is Active"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","ref_group_id","title","content_type","evidence_level","geographic_relevance","consensus_score","composite_trust_score","source_status","coi_bypassed","is_active","created_at"],"title":"ReferenceResponse"},"ReferenceSubmit":{"properties":{"title":{"type":"string","title":"Title"},"url":{"type":"string","title":"Url"},"publication_date":{"type":"string","format":"date","title":"Publication Date"},"ref_group_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Ref Group Id"},"ref_group_data":{"anyOf":[{"$ref":"#/components/schemas/ReferenceGroupCreate"},{"type":"null"}]},"source_specific_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Specific Note"},"doi":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Doi"},"authors":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Authors"},"journal_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Journal Name"},"impact_factor":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Impact Factor"},"content_type":{"type":"string","title":"Content Type","default":"webpage"},"evidence_level":{"type":"string","title":"Evidence Level","default":"review"},"target_populations":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Target Populations"},"topics":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Topics"},"geographic_relevance":{"type":"string","title":"Geographic Relevance","default":"global"},"consensus_score":{"type":"number","title":"Consensus Score","default":0.5},"source_file_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source File Hash"}},"type":"object","required":["title","url","publication_date"],"title":"ReferenceSubmit","description":"Submit a new reference source through the full ingestion pipeline.\n\nThe pipeline will:\n  1. Resolve or create the reference group\n  2. Check the trust score (reject if too low or too old)\n  3. Run a conflict-of-interest check via LLM (flag if clear industry interest)\n  4. Generate a focused summary of the content (main findings, methods, conclusions)\n  5. Embed the summary for RAG retrieval\n\nref_group resolution (exactly one must be provided):\n  - ref_group_id: UUID of an existing reference group in the DB\n  - ref_group_data: JSON object describing a new group to create"},"ReferenceSubmitResponse":{"properties":{"reference":{"$ref":"#/components/schemas/ReferenceResponse"},"pipeline_result":{"additionalProperties":true,"type":"object","title":"Pipeline Result"},"message":{"type":"string","title":"Message"}},"type":"object","required":["reference","pipeline_result","message"],"title":"ReferenceSubmitResponse","description":"Response returned from POST /api/references/submit."},"ReferencesSearchRequest":{"properties":{"query":{"type":"string","maxLength":1000,"minLength":1,"title":"Query","description":"Free-text search query. Returns the most semantically relevant references.","examples":["creatine adolescents safety"]},"max_results":{"type":"integer","maximum":20.0,"minimum":1.0,"title":"Max Results","description":"Maximum number of references to return. Capped at 20.","default":10},"published_after":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Published After","description":"Only return references published on or after this ISO-8601 date."}},"type":"object","required":["query"],"title":"ReferencesSearchRequest","description":"Semantic search over the curated reference library — no LLM generation.","examples":[{"max_results":10,"query":"creatine adolescents safety"},{"query":"intermittent fasting weight loss"}]},"ReferencesSearchResponse":{"properties":{"query":{"type":"string","title":"Query","description":"Echo of the original query."},"count":{"type":"integer","minimum":0.0,"title":"Count","description":"Number of references returned."},"results":{"items":{"$ref":"#/components/schemas/PublicSource"},"type":"array","title":"Results","description":"References ranked by semantic relevance × trust score."}},"type":"object","required":["query","count"],"title":"ReferencesSearchResponse","description":"Ranked references for a query, without an LLM-generated answer.","examples":[{"count":1,"query":"creatine adolescents safety","results":[{"evidence_level":"review","excerpt":"There is no compelling scientific evidence that the short- or long-term use of creatine monohydrate has detrimental effects on otherwise healthy individuals...","id":"8f4e1c8a-9b6d-4f3e-9a12-0e7d2b6c1a44","published_at":"2021-02-08T00:00:00Z","publisher":"Journal of the International Society of Sports Nutrition","publisher_short_name":"JISSN","title":"Common questions and misconceptions about creatine supplementation","trust_score":0.78,"url":"https://doi.org/10.1186/s12970-021-00412-w"}]}]},"SendMessageRequest":{"properties":{"content":{"type":"string","title":"Content"},"filters":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Filters"},"deep_research":{"type":"boolean","title":"Deep Research","default":false},"preview_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Preview Token"},"model":{"type":"string","title":"Model","default":"auto"}},"type":"object","required":["content"],"title":"SendMessageRequest"},"SendMessageResponse":{"properties":{"message":{"$ref":"#/components/schemas/ChatMessageResponse"},"user_message_id":{"type":"string","title":"User Message Id"},"chat_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Chat Title"},"final_prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Final Prompt"},"model_notice":{"anyOf":[{"$ref":"#/components/schemas/ModelNotice"},{"type":"null"}]}},"type":"object","required":["message","user_message_id"],"title":"SendMessageResponse"},"ShareChatResponse":{"properties":{"is_public":{"type":"boolean","title":"Is Public"},"public_slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Public Slug"}},"type":"object","required":["is_public"],"title":"ShareChatResponse"},"SourceResponse":{"properties":{"id":{"type":"string","title":"Id"},"title":{"type":"string","title":"Title"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"group_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Group Id"},"group_name":{"type":"string","title":"Group Name"},"group_short_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Group Short Name"},"evidence_level":{"type":"string","title":"Evidence Level"},"composite_trust_score":{"type":"number","title":"Composite Trust Score"},"published_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Published At"},"chunk_text":{"type":"string","title":"Chunk Text"},"passage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Passage"},"test_count":{"type":"integer","title":"Test Count","default":0},"test_requested":{"type":"boolean","title":"Test Requested","default":false}},"type":"object","required":["id","title","group_name","evidence_level","composite_trust_score","chunk_text"],"title":"SourceResponse"},"UpdateChatTitleRequest":{"properties":{"title":{"type":"string","title":"Title"}},"type":"object","required":["title"],"title":"UpdateChatTitleRequest"},"UserPreferences":{"properties":{"child_ages_months":{"items":{"type":"integer"},"type":"array","title":"Child Ages Months","default":[]},"dietary_prefs":{"items":{"type":"string"},"type":"array","title":"Dietary Prefs","default":[]},"health_conditions":{"items":{"type":"string"},"type":"array","title":"Health Conditions","default":[]},"location":{"type":"string","title":"Location","default":"US"},"chat_edit_preference":{"type":"string","title":"Chat Edit Preference","default":"ask"},"family_members":{"items":{"$ref":"#/components/schemas/FamilyMember"},"type":"array","title":"Family Members","default":[]},"dob_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Dob Year"},"dob_month":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Dob Month"},"dob_day":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Dob Day"},"gender":{"anyOf":[{"type":"string","enum":["Male","Female"]},{"type":"null"}],"title":"Gender"},"health_goals":{"items":{"type":"string"},"type":"array","title":"Health Goals","default":[]},"tour_completed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Tour Completed"},"sources_tour_completed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Sources Tour Completed"},"source_filters":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Source Filters"}},"type":"object","title":"UserPreferences"},"UserProfileUpdate":{"properties":{"full_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Full Name"},"preferences":{"anyOf":[{"$ref":"#/components/schemas/UserPreferences"},{"type":"null"}]},"height":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Height"},"weight":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Weight"},"notify_newsletter":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Notify Newsletter"},"suppressed_ref_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Suppressed Ref Ids"},"suppressed_ref_group_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Suppressed Ref Group Ids"},"trust_overrides":{"anyOf":[{"additionalProperties":{"type":"number"},"type":"object"},{"type":"null"}],"title":"Trust Overrides"},"ref_weight_overrides":{"anyOf":[{"additionalProperties":{"type":"number"},"type":"object"},{"type":"null"}],"title":"Ref Weight Overrides"},"ref_group_weight_overrides":{"anyOf":[{"additionalProperties":{"type":"number"},"type":"object"},{"type":"null"}],"title":"Ref Group Weight Overrides"},"onboarding_completed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Onboarding Completed"}},"type":"object","title":"UserProfileUpdate"},"UserResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"email":{"type":"string","title":"Email"},"firebase_uid":{"type":"string","title":"Firebase Uid"},"avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar Url"},"full_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Full Name"},"preferences":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Preferences"},"height":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Height"},"weight":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Weight"},"suppressed_ref_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Suppressed Ref Ids"},"suppressed_ref_group_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Suppressed Ref Group Ids"},"trust_overrides":{"anyOf":[{"additionalProperties":{"type":"number"},"type":"object"},{"type":"null"}],"title":"Trust Overrides"},"ref_weight_overrides":{"anyOf":[{"additionalProperties":{"type":"number"},"type":"object"},{"type":"null"}],"title":"Ref Weight Overrides"},"ref_group_weight_overrides":{"anyOf":[{"additionalProperties":{"type":"number"},"type":"object"},{"type":"null"}],"title":"Ref Group Weight Overrides"},"points":{"type":"integer","title":"Points","default":0},"notify_newsletter":{"type":"boolean","title":"Notify Newsletter","default":true},"onboarding_completed":{"type":"boolean","title":"Onboarding Completed"},"is_active":{"type":"boolean","title":"Is Active"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"last_login":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Login"}},"type":"object","required":["id","email","firebase_uid","onboarding_completed","is_active","created_at"],"title":"UserResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VectorSearchRequest":{"properties":{"query":{"type":"string","title":"Query"},"limit":{"type":"integer","title":"Limit","default":20},"filters":{"anyOf":[{"$ref":"#/components/schemas/ReferenceFilters"},{"type":"null"}]}},"type":"object","required":["query"],"title":"VectorSearchRequest"}},"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}}},"tags":[{"name":"public","description":"**Public, no-auth API for external developers and AI agents.** Stable schema, rate-limited (10 req / IP / UTC day). Start here.","externalDocs":{"description":"Developer docs","url":"https://docs.allnutrition.info/"}},{"name":"ask","description":"Internal Ask endpoint used by the AllNutrition web app (requires auth)."},{"name":"ask-external","description":"Token-authenticated Ask endpoint for partners (bearer token required)."},{"name":"chat","description":"Multi-turn chat sessions (requires auth)."},{"name":"references","description":"Reference library management (requires auth)."},{"name":"users","description":"User profile + preferences (requires auth)."},{"name":"auth","description":"Authentication helpers."},{"name":"newsletter","description":"Newsletter sign-up endpoints."},{"name":"tests","description":"Knowledge-test endpoints (requires auth)."},{"name":"transcribe","description":"Audio transcription helpers."}],"externalDocs":{"description":"AllNutrition developer documentation","url":"https://docs.allnutrition.info"}}