Recipe APIDeveloper documentation
Download OpenAPI ↗
RECIPE SCORING API

Authenticate your server, submit ingredients, and receive a score for each recipe.

POST

Algorithm:  ·  Environment:

01

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
Request an access token · cURL

          
Reuse tokens until shortly before the returned expires_in period ends.
02

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
03

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.

200 OK · Illustrative score-only response

          

The score above is an example, not a calculated result. Each request uses this deployment’s selected algorithm.

04

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.
Submit recipes individually. This API has no batch endpoint. Start with sequential requests.