canonical: https://jentic.com/apis/noms.sh/noms

# Noms Sh Noms API

The Noms API serves nutritional reference data for foods, brands, nutrients, and food groups over a read-focused REST interface. A client can search foods with typo-tolerant text search, look a product up by barcode, filter by brand or food group, and sort results by a nutrient's per-100 g or ml value. Food records can embed their brand, food group, nutrients, serving sizes, images, and market countries in one response, and decimals arrive as strings to keep full precision. Account endpoints report request usage and set the market (country) that food results are scoped to.

## For AI agents

Search foods by name or barcode, read per-100 g nutrient values, and look up brands, nutrients, and food groups from the Noms nutrition database.

## Scope

Does not handle recipe search, meal logging, diet tracking, or grocery ordering. Use for looking up food, brand, and nutrient reference data only.

## Capabilities

- Search foods with typo-tolerant text search through the q parameter on GET `/v1/foods`
- Look up a packaged product by barcode and embed its brand, nutrients, and serving sizes with include
- Rank foods by a nutrient's per-100 value, for example sorting by -nutrient[PROTEIN]
- Browse the nutrient, brand, and food group reference lists and fetch any single record by id
- Check the account's request usage and quota before running a large lookup job
- Set the market (country) that food results are scoped to with PUT `/v1/market`

## Use cases

### Nutrition lookup for an AI meal assistant

An AI meal-planning assistant needs real nutrient values instead of guessed ones. Through Jentic the agent searches for 'look up nutrition facts for a food', gets the Noms food search operation with its input schema, and calls it with a q search plus include=nutrients,serving_sizes so the macros and portion weights arrive in one response. The X-API-Key is attached at call time, so the agent works from returned data, not memory.

Example prompt: Call GET `/v1/foods` with q=greek yogurt and include=nutrients,serving_sizes, then report the protein and energy values per serving for the top match

### Barcode scan to nutrient panel

A grocery or fitness app scans a product barcode and needs the matching food record. The Noms barcode filter on GET `/v1/foods` returns the product, and include=brand,nutrients,images embeds the brand, nutrient values, and product images so the app can render a full nutrition panel from a single call. Decimal values arrive as strings, so the app keeps the published precision.

Example prompt: Call GET `/v1/foods` with barcode=5000159484695 and include=brand,nutrients,images, then return the brand name and the energy, fat, and sugar values

### High-protein food ranking

A diet coach wants a shortlist of foods ordered by a single nutrient. Noms sorts foods by a nutrient's per-100 g or ml value with sort=-nutrient[PROTEIN], and foods that lack the nutrient rank last rather than being dropped. Nutrient codes come from GET `/v1/nutrients`, so the same pattern works for fibre, iron, or any other listed nutrient.

Example prompt: Call GET `/v1/nutrients` with q=protein to confirm the nutrient code, then call GET `/v1/foods` with q=beans and sort=-nutrient[PROTEIN] and list the top results with their protein values

### Market and quota housekeeping

On single-market plans, food results are scoped to one country, and an account must pick it before food requests succeed. An integration can read the current selection with GET `/v1/market`, change it with PUT `/v1/market` by passing the required market field, and check remaining allowance with GET `/v1/usage` before starting a batch of lookups.

Example prompt: Call GET `/v1/usage` to read the remaining quota, then call PUT `/v1/market` with market set to GB and confirm the new selection in the response

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/v1/foods` | Search and filter foods |
| GET | `/v1/foods/{id}` | Get a food |
| GET | `/v1/nutrients` | List nutrients |
| GET | `/v1/brands` | List brands |
| GET | `/v1/food-groups` | List food groups |
| GET | `/v1/usage` | Get usage and quota |
| PUT | `/v1/market` | Set the market selection |

## Key resources

- **Foods** — Food and product records with barcode, brand, food group, nutrients, serving sizes, images, and market countries
- **Nutrients** — Nutrient definitions with codes and units used for filtering and sorting foods
- **Brands and food groups** — Reference lists that foods link to, each searchable and fetchable by id
- **Account usage and market** — Request quota for the account and the market (country) food results are scoped to

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 76 / 100
- **Maturity:** AI-Ready
- **Dimensions:**
  - Foundational Compliance: 99 / 100
  - Developer Experience & Jentic Compatibility: 72 / 100
  - AI-Readiness & Agent Experience: 67 / 100
  - Agent Usability: 94 / 100
  - Security: 50 / 100
  - AI Discoverability: 98 / 100
- **View full report:** https://jentic.com/apis/noms.sh/noms/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Noms by hand means sending the X-API-Key header, following links.next for keyset pagination, and handling free-tier 403 rules such as the market selection. Through Jentic you install once, import Noms from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Noms reads sit at their own URL paths such as `/v1/foods` and `/v1/nutrients`, while the one write, PUT `/v1/market`, changes the account's market for every key. You choose the operations your agent may call, so that write is not included unless you add it.
- **Credential handling:** Your Noms API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'look up nutrition facts for a food' or 'find a product by barcode', and Jentic returns the matching Noms operation with its input schema, including the q, barcode, include, and sort parameters, so the agent calls the right endpoint directly.

## Related APIs

- **Nutritionix API** — Nutrition database with natural-language food parsing and restaurant items
- **Edamam Food Database API** — Food and nutrient database with ingredient parsing
- **Open Food Facts** — Open, crowd-sourced database of packaged food products
- **spoonacular API** — Recipe search and meal planning built on ingredient data

## FAQ

### What authentication does the Noms API use?

Per its OpenAPI spec, the Noms API authenticates with an API key sent in the X-API-Key header, in the noms_sk_ format, created in the Noms dashboard under API Keys. Through Jentic, the key is held by your own instance and attached to each call, so your agent never sees the raw value.

### Can I look up a food by barcode with the Noms API?

Yes. GET `/v1/foods` accepts a barcode filter, and you can add include=brand,nutrients,serving_sizes to embed the related records in the same response. If you already have the Noms id, GET `/v1/foods/{id}` returns the single food directly.

### What are the rate limits for the Noms API?

The spec describes a per-account request quota set by your plan, shared by every key you own, over a rolling 24-hour window on the free plan and your billing period on paid plans. Responses carry RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers, and GET `/v1/usage` reports where you stand. Check the Noms pricing page at https://noms.sh for the allowance on each plan.

### Why does the Noms API return a 403 on a food search?

On the free tier, list endpoints need a q search rather than a bare or filter-only listing, results are capped in depth, and foods requests fail until a market is selected. Choose the market with PUT `/v1/market`, keep a q term on list calls, or move to a paid tier, which the spec says lifts all three limits.

### How do I get nutrition facts for a food through Jentic?

Search Jentic for 'look up nutrition facts for a food', load the Noms food search operation, and call GET `/v1/foods` with a q term and include=nutrients,serving_sizes. Your agent reads the per-100 values and portion weights straight from the response. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Is there a Noms MCP server?

You do not need an MCP server to give your agent Noms. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent calls the food, nutrient, and brand operations it needs on demand.

### Can I limit what my agent is allowed to do with the Noms API?

Yes. Write a rule that allows the food, nutrient, brand, and food group read operations plus GET `/v1/usage`, and the agent can search and read nutrition data without being able to call PUT `/v1/market.` Its calls are logged, so you can review what it looked up.