Authenticate your server, submit ingredients, and receive a score for each recipe.
Authenticate your server
Use the client ID and secret supplied to your integration team to request an access token. Send that token with every scoring request.
- Token URL
- Client ID
- Scope
- Grant type
client_credentials
expires_in period ends.
Score a recipe
Send one recipe per request. Use NDSR food IDs from the supplied food catalog and unit IDs from the reference below. Send IDs as strings, not descriptions or your own food IDs.
| Field | Type | Description |
|---|---|---|
recipe_idRequired |
string | Your recipe reference, up to 160 characters. |
nameRequired |
string | Recipe name, up to 160 characters. |
servingsizeRequired |
number / numeric string | A number greater than zero. |
ingredientsRequired |
array |
1–300 items with an NDSR food ID (food_id), nonnegative decimal
quantity and unit.
|
Ingredient fields
| Field | Description |
|---|---|
food_id |
NDSR food ID from the supplied food catalog, as a string. |
quantity |
Nonnegative decimal amount in the selected unit. |
unit |
Unit ID from the reference below, as a string. |
Units
Send the ID in ingredients[].unit. For example,
"quantity": "2400", "unit": "13" means 2,400 grams.
| Unit ID | Unit |
|---|---|
1 |
Teaspoon |
2 |
Tablespoon |
3 |
Ounce |
4 |
Cup |
5 |
Pint |
6 |
Quart |
7 |
Gallon |
8 |
Dash |
9 |
Smidgen |
10 |
Drop |
11 |
Pinch |
12 |
Pounds |
13 |
Grams |
14 |
Kilogram |
Use the result
A successful score only response returns your recipe reference, a numeric score and the algorithm version. Store these with your recipe to track the result.
Errors & request limits
| Status | What to do |
|---|---|
| 400 · Invalid request | Check required fields, ingredient IDs, quantities and servings. |
| 401 · Unauthorized | Obtain a valid access token for this deployment’s client. |
| 403 · Forbidden | Check the token’s scope and that the project is active. |
| 429 · Too many requests | Reduce request concurrency and retry with exponential backoff. |
| 500 / 502 / 503 / 504 | Scoring failed or is unavailable. Retry cautiously; contact your integration team if it persists. |