RAMROKNutrition Cloud

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.

GroupNutrition fields
Energy and macrosEnergy (calories), Protein, Total fat, Carbohydrate
Fats and cholesterolSaturated fat, Trans fat, Monounsaturated fat, Polyunsaturated fat, Cholesterol, Omega-3 fat
Other label valuesFiber, Total sugars, Added sugars, Alcohol, Starch, Sugar alcohols
VitaminsVitamin 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
MineralsSodium, 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/portions

150 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.

Open developer portal