API Reference

Base URL: https://api.cooktool.org/v1. All endpoints require the x-api-key header. Responses are JSON. HTTP status codes follow REST conventions.

Quick start

Create a free account to get your API key.
Copy the key — it is only shown once. Store it securely.
Pass the key in every request via the x-api-key header.

cURL

bash

# 1. Get your free API key at api.cooktool.org/signup
# 2. Make your first request
curl "https://api.cooktool.org/v1/search?q=chicken" \
  -H "x-api-key: ctk_live_YOUR_KEY_HERE"

JavaScript

javascript

const res = await fetch(
  'https://api.cooktool.org/v1/ingredients/42?',
  { headers: { 'x-api-key': 'ctk_live_YOUR_KEY_HERE' } }
);
const data = await res.json();
console.log(data.name, data.nutrients[0]);

Python

python

import requests

r = requests.get(
    'https://api.cooktool.org/v1/ingredients/42',
    headers={'x-api-key': 'ctk_live_YOUR_KEY_HERE'}
)
print(r.json()['name'])

Authentication

All API requests must include your API key in the x-api-key HTTP header. Keys follow the format ctk_live_<32-hex-chars>.

bash

curl https://api.cooktool.org/v1/nutrients \
  -H "x-api-key: ctk_live_a1b2c3d4e5f6..."

200 OK

Request succeeded

401 Unauthorized

Missing or invalid API key

429 Too Many Requests

Rate limit exceeded — slow down or upgrade

Rate limits

Plan	Requests / day	Requests / second	API keys
Free	1,000	5	1
Pro	20,000	20	2
Enterprise	20,000	50	5

When you exceed the rate limit, the API returns 429 Too Many Requests. The daily counter resets at UTC midnight.

Ingredients

GET/v1/ingredients

List canonical ingredients. Supports free-text search, category filter, and allergen filter.

Parameters

Name	Type	Description
`q`	string	Free-text search on ingredient name
`category`	integer	Filter by category_id
`allergen`	string	Filter by allergen (gluten, dairy, eggs, nuts…)
`limit`	integer	Max results (default 20, max 100)
`offset`	integer	Pagination offset (default 0)

Example

bash

curl "https://api.cooktool.org/v1/ingredients?q=chicken&allergen=eggs&limit=5" \
  -H "x-api-key: ctk_live_..."

Response

json

{ "data": [ { "id": 42, "name": "Chicken breast, raw", "category_id": 5, "data_type": "sr_legacy" } ], "limit": 5, "offset": 0 }

GET/v1/ingredients/:id

Get a single ingredient with full nutrient profile, density data, and allergen list.

Parameters

Name	Type	Description
`id`*	integer	Ingredient ID

Example

bash

curl "https://api.cooktool.org/v1/ingredients/42" -H "x-api-key: ctk_live_..."

Response

json

{
  "id": 42, "name": "Chicken breast, raw", "category_id": 5,
  "nutrients": [ { "nutrient_id": 1, "name": "Energy", "unit": "kcal", "amount": 165 } ],
  "density": { "g_per_ml": 1.02, "g_per_cup": 240.5, "source": "usda" },
  "allergens": []
}

Nutrients (country-resolved)

GET/v1/ingredients/:id/nutrients

Returns the best verified national nutrient values for the requested country, falling back to USDA SR for any nutrient not covered by the national database.

Parameters

Name	Type	Description
`id`*	integer	Ingredient ID
`country`	string	ISO 3166-1 alpha-2 country code (GB, DE, FR, SE, NO, DK). Defaults to US.

Example

bash

curl "https://api.cooktool.org/v1/ingredients/42/nutrients?country=DE" \
  -H "x-api-key: ctk_live_..."

Response

json

{
  "id": 42, "name": "Chicken breast, raw", "country": "DE",
  "nutrients": [
    { "nutrient_id": 1, "name": "Energy", "unit": "kcal", "amount": 110, "source": "bls" },
    { "nutrient_id": 2, "name": "Protein", "unit": "g",   "amount": 23.1, "source": "bls" },
    { "nutrient_id": 3, "name": "Omega-3", "unit": "g",   "amount": 0.04, "source": "usda_fallback" }
  ]
}

CO₂ footprint

GET/v1/ingredients/:id/carbon

Returns the ISO 14040-compliant GHG intensity (kg CO₂e / kg food) for the ingredient, with source dataset, DQR score, and uncertainty range.

Parameters

Name	Type	Description
`id`*	integer	Ingredient ID
`country`	string	Prefer AGRIBALYSE values for FR/EU context when country=FR. Defaults to global average.

Example

bash

curl "https://api.cooktool.org/v1/ingredients/42/carbon?country=FR" \
  -H "x-api-key: ctk_live_..."

Response

json

{
  "id": 42, "name": "Chicken breast, raw",
  "carbon": {
    "kg_co2e_per_kg": 6.9,
    "source": "poore_nemecek_2018",
    "dqr": 1,
    "boundary": "cradle_to_retail",
    "uncertainty_low": 5.1,
    "uncertainty_high": 10.2,
    "unit": "kg CO2e / kg food"
  }
}

Yield factors

GET/v1/ingredients/:id/yield

Returns the yield factor and nutrient retention factors for a given cooking method. Multiply raw nutrient amounts by the retention factor to get cooked values.

Parameters

Name	Type	Description
`id`*	integer	Ingredient ID
`method`	string	Cooking method: boiling, frying, baking, steaming, grilling. Default: boiling.

Example

bash

curl "https://api.cooktool.org/v1/ingredients/42/yield?method=grilling" \
  -H "x-api-key: ctk_live_..."

Response

json

{
  "id": 42, "name": "Chicken breast, raw", "method": "grilling",
  "yield_factor": 0.74,
  "nutrient_retention": {
    "protein": 1.00, "fat": 0.96, "energy": 0.97,
    "vitamin_b1": 0.79, "vitamin_b6": 0.77
  }
}

Unit conversion

GET/v1/ingredients/:id/convert

Convert between weight, volume, and piece units using ingredient-specific density and piece-weight data.

Parameters

Name	Type	Description
`id`*	integer	Ingredient ID
`from`*	string	Source unit (g, kg, oz, lb, ml, l, cup, tbsp, tsp, piece)
`to`*	string	Target unit (same set as from)
`amount`*	number	Amount in source unit

Example

bash

curl "https://api.cooktool.org/v1/ingredients/1001/convert?from=cup&to=g&amount=2" \
  -H "x-api-key: ctk_live_..."

Response

json

{
  "id": 1001, "name": "Butter, salted",
  "from": { "unit": "cup", "amount": 2 },
  "to":   { "unit": "g",   "amount": 454 },
  "density_source": "usda"
}

Survey foods

GET/v1/survey-foods

List FNDDS survey foods (Tier 2). Filter by WWEIA category code.

Parameters

Name	Type	Description
`q`	string	Free-text search
`wweia`	integer	WWEIA category code filter
`limit`	integer	Max results (default 20, max 100)
`offset`	integer	Pagination offset

Example

bash

curl "https://api.cooktool.org/v1/survey-foods?q=pizza&limit=5" -H "x-api-key: ctk_live_..."

GET/v1/survey-foods/:id/components

Decompose a survey food into its Tier-1 canonical ingredients with gram amounts.

Parameters

Name	Type	Description
`id`*	integer	Survey food ID

Example

bash

curl "https://api.cooktool.org/v1/survey-foods/1001/components" -H "x-api-key: ctk_live_..."

Branded products

GET/v1/branded

Search 2M+ branded food products. Look up by GTIN/UPC barcode or brand name.

Parameters

Name	Type	Description
`q`	string	Free-text search on product name
`gtin`	string	Exact GTIN/UPC barcode lookup
`brand`	string	Partial brand owner name match
`limit`	integer	Max results (default 20, max 100)
`offset`	integer	Pagination offset

Example

bash

curl "https://api.cooktool.org/v1/branded?gtin=00038000138416" -H "x-api-key: ctk_live_..."

Search

GET/v1/search

Cross-tier unified search. Returns up to 10 results per tier. Pass country= to prioritise national source names.

Parameters

Name	Type	Description
`q`*	string	Search query (min 1 char)
`country`	string	ISO country code to prefer national name matches (GB, DE…)

Example

bash

curl "https://api.cooktool.org/v1/search?q=tomato&country=DE" -H "x-api-key: ctk_live_..."

Response

json

{
  "query": "tomato", "country": "DE",
  "results": [
    { "id": 123, "name": "Tomate, roh",          "tier": "ingredient",  "source": "bls"    },
    { "id": 456, "name": "Tomato soup, canned",  "tier": "survey_food", "source": "fndds"  },
    { "id": 789, "name": "Hunt's Diced Tomatoes","tier": "branded",     "source": "branded" }
  ]
}

Nutrient list

GET/v1/nutrients

List all nutrient definitions (id, usda_id, name, unit). Useful for mapping nutrient_id values in other responses.

Example

bash

curl "https://api.cooktool.org/v1/nutrients" -H "x-api-key: ctk_live_..."

API Reference

Quick start

Authentication

Rate limits

Ingredients

Nutrients (country-resolved)

CO₂ footprint

Yield factors

Unit conversion

Survey foods

Branded products

Search

Nutrient list

Categories