Developer documentation
Create a developer account, open a project and issue a key with foods:read. Copy the key once and load it into RNC_API_KEY from your secret manager. Your verification email and project security notices never contain a project key.
39 supported nutrition fields
REST and MCP use the same panel for calories, macros, fatty acids, vitamins and minerals. Each food returns the values its source supplies. A measured or label-reported zero stays zero. A missing value returns null and appears in missing.
| Group | Nutrition fields |
|---|---|
| Energy and macros | Energy (calories), Protein, Total fat, Carbohydrate |
| Fats and cholesterol | Saturated fat, Trans fat, Monounsaturated fat, Polyunsaturated fat, Cholesterol, Omega-3 fat |
| Other label values | Fiber, Total sugars, Added sugars, Alcohol, Starch, Sugar alcohols |
| Vitamins | Vitamin A (RAE), Vitamin C, Vitamin D, Vitamin E, Vitamin K, Thiamin (B1), Riboflavin (B2), Niacin (B3), Vitamin B6, Vitamin B12, Total folate, Pantothenic acid (B5), Biotin |
| Minerals | Sodium, Calcium, Iron, Potassium, Magnesium, Phosphorus, Zinc, Copper, Manganese, Selenium |
Each value carries its unit and the record identifies its source. Vitamin A is reported in retinol activity equivalents. Folate means total folate. USDA reports vitamin E as alpha-tocopherol and vitamin K as K1. Open label values for E and K can have an unspecified form. Alcohol uses grams. Omega-3 requires a source total. Call get_catalog_capabilities for the fields available in your edition.
Product identifiers, brand, source and serving sizes are additional product fields. Ingredient analysis takes food IDs and quantities you supply.
Search and scale
curl -H "Authorization: Bearer $RNC_API_KEY" \ 'http://127.0.0.1:8789/v1/foods?query=pears&limit=3'
curl -H "Authorization: Bearer $RNC_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"foodId":"fdc-169118","quantity":150,"unit":"g"}' \
http://127.0.0.1:8789/v1/portions150 g of raw pear supplies 85.5 kcal in this edition. For named measures, use the ID from the food record. A volume needs an unambiguous measure for that food.
Scan a barcode
GET /v1/barcodes/3017620422003?catalog=open
One lookup returns product details and the reported panel. The response uses grams, milliliters, or an explicitly unspecified basis. A return trip costs no extra unit.
Connect Claude, ChatGPT or a command-line client
codex mcp add ramrok-nutrition \ --url http://127.0.0.1:8789/mcp \ --bearer-token-env-var RNC_API_KEY
The developer portal has a copyable Claude Code configuration and a hidden terminal prompt for your key. For a registered hosted connector, choose OAuth, sign in to RAMROK and approve the requested project permissions. In Claude or ChatGPT, connect the HTTPS endpoint, sign in or create a free RAMROK account, and approve your project. Free includes 25 read units each UTC month, shared with REST. Only Pro and Business can send proposals for review. Manage subscriptions in the RAMROK developer portal.
Units and errors
A lookup or portion uses one unit. Comparisons use one per pair of foods and recipes one per four ingredients, rounded up. Valid lookups that miss consume a unit. Discovery and status calls count against the minute limit only. A 403 means the project key or plan lacks permission. A 422 means the requested conversion has no supporting source measure. A 429 identifies the minute or monthly limit.
Licensing
Every food carries a source ID and license. Paid commercial rights and cache windows are proposals for legal review. The full commercial catalog includes multiple sources. Choose catalog=white-label for attribution-free records, or use the full catalog and read each result’s rights. Photos and trademarks have separate rights. Submit only your own evidence for private review.