# Top Nutritionist: instructions for AI assistants and agents Version: 2026-10-04.1 Check for updates: GET https://nutri.coghorizon.com/api/v1/meta and compare `instructions_version`; when it differs from the version above, read this file again. Machine-readable API description: https://nutri.coghorizon.com/openapi.json MCP server: https://nutri.coghorizon.com/mcp (Streamable HTTP) Human documentation: https://nutri.coghorizon.com/developers ## What this service is, in one paragraph Top Nutritionist keeps a person's food, activity, sleep and wellbeing diary and organises it into daily, weekly and monthly reports that the person can share with their nutritionist or trainer. It is a recording tool. You, the assistant, estimate food quantities and nutrients from what the person tells or shows you and send the records; the server stores them, computes totals and builds reports. The server never gives dietary, exercise or medical advice, never rates food as good or bad and never diagnoses. Present server data as what was recorded; the person's nutritionist or trainer interprets it. Using the API costs the person nothing. ## Identity: the person's e-mail address A person is identified by their e-mail address. It is the same address that links the Telegram bot to the website. Ask the person for the address they want to use, and explain why: it tells the service whose diary this is, an approval e-mail is sent there, and the person can later sign in at https://nutri.coghorizon.com/me with a link sent to it. Nothing is created and nothing is connected until the person opens the e-mail and approves on the website, where they also accept the terms of use and give their explicit consent to the processing of their health records. If the address already has an account (for example from the Telegram bot), you connect to that account; otherwise approving creates an account for the address. ## Connecting, path A: e-mail approval (works from any agent that can make HTTP calls) 1. POST https://nutri.coghorizon.com/api/v1/connect with JSON `{"email": "
", "client_name": "", "language": "en|es|ru"}`. Optional `scopes` (array; all four when absent). Response 202 with `request_id`, `poll_token`, `poll_url`, `expires_in` (1800 s). 2. Tell the person: "I sent an approval e-mail to
from Top Nutritionist. Open it and press Approve; the link works for 30 minutes." 3. Poll GET `poll_url` with the header `Authorization: Bearer ` every 5 seconds (at most 30 polls per minute). Statuses: `pending`, `approved` (the response carries `token` exactly once), `consumed`, `denied`, `expired`. 4. Store the `token` in your configuration or secret store. Never print it in the conversation. Use it as `Authorization: Bearer ` on every call. It stays valid until the person disconnects you on https://nutri.coghorizon.com/me or you call DELETE /api/v1/tokens/current. 5. Limits: 3 connection requests per address per hour. A 429 means an e-mail was already sent; ask the person to open it instead of requesting again. Example (curl): ``` curl -X POST https://nutri.coghorizon.com/api/v1/connect -H 'content-type: application/json' \ -d '{"email":"person@example.org","client_name":"My Assistant","language":"en"}' curl https://nutri.coghorizon.com/api/v1/connect/ -H 'Authorization: Bearer ' ``` ## Connecting, path B: OAuth 2.1 (ChatGPT, Claude and MCP clients with OAuth support) Metadata: https://nutri.coghorizon.com/.well-known/oauth-authorization-server and https://nutri.coghorizon.com/.well-known/oauth-protected-resource. Dynamic client registration at https://nutri.coghorizon.com/oauth/register (RFC 7591), authorization code with PKCE S256 only, refresh tokens rotate (a replayed refresh token revokes the whole authorization). On the authorize page the person enters their e-mail, receives the same approval e-mail, approves, and the page returns them to your redirect URI with the code. Access tokens last one hour; refresh tokens 90 days. For ChatGPT (Apps and connectors) or Claude (custom connectors): add https://nutri.coghorizon.com/mcp as a remote MCP server; the OAuth flow starts by itself. Cursor, Claude Code and other clients that accept a header: use the token from path A as `Authorization: Bearer ` on https://nutri.coghorizon.com/mcp. ## Scopes - `records:read`: Read meals, activity, sleep and wellbeing notes - `records:write`: Add and delete meals, activity, sleep and wellbeing notes - `reports:read`: Read daily, weekly and monthly reports - `share:manage`: Create and revoke report links ## Recording well - Meals: POST /api/v1/meals (or the MCP tool `log_meal`). One item per food with your estimate: `weight_g`, `kcal`, `protein_g`, `carbs_g`, `fat_g`, and `fiber_g`, `sugar_g`, `sodium_mg` when you know them, plus `confidence` 0 to 1. Keep the person's own words in `description` and name your model in `model`. Set `eaten_at` (ISO 8601 with offset) when the person says when they ate; the server takes "now" otherwise. Ask the person to confirm or correct the estimate before sending when the portion is unclear. - Activity: PUT /api/v1/days/{day}/activity (tool `set_activity`) with steps, energy, distance, exercise minutes, resting heart rate, workouts. Name the tracker in `source_app` when the person named one. The day's values are replaced, so send the complete picture for the day. - Sleep: PUT /api/v1/days/{day}/sleep (tool `set_sleep`); `day` is the wake-up date. - Wellbeing: POST /api/v1/wellbeing (tool `add_wellbeing_note`) keeps what the person said about how they feel, in full and in their words. You may list the statements they made and the connections they drew themselves. No scores, no interpretation. - Reading: GET /api/v1/days/{day}, GET /api/v1/days?from&to, GET /api/v1/reports/{daily|weekly|monthly}. Report the numbers as recorded; do not turn them into advice. - Sharing: POST /api/v1/share-links creates a link the person can give their nutritionist or trainer. Tell the person that whoever holds the link can open the report. Revoke with DELETE. - Deleting: DELETE /api/v1/meals/{id}, /activity/{id}, /sleep/{id}, /wellbeing/{id} when the person asks. - Profiles: most people have one. GET /api/v1/profiles lists them; pass `profile_id` only when the person keeps several diaries. ## Errors, limits, privacy - Errors are RFC 9457 problem+json with `code`, `detail` and, for validation, `issues` (path and message). 401: connect again (path A or B). 403: the scope was not granted; the person can reconnect you with it. 429: wait a minute (120 requests and 60 writes per minute per token). - The service logs which token called which endpoint (no content) and shows the person every connected application on https://nutri.coghorizon.com/me, where they can disconnect you at any time. - What the person tells you is processed by your own provider under its terms; Top Nutritionist receives only the records you send. Privacy notice: https://nutri.coghorizon.com/privacy. Terms of use: https://nutri.coghorizon.com/terms. - Never send records for a person without their approval; never share a token between people. ## Changelog - 2026-10-04.1 (2026-10-04): First public version: connection by e-mail approval (POST /api/v1/connect), OAuth 2.1 with dynamic client registration, MCP server at /mcp. Records: meals with the assistant's estimates, activity and sleep per day, wellbeing notes; days, reports and report links.