Base URL: https://compkitchen.com
Every endpoint returns JSON (CSV export aside). There is no SDK and no versioned path
prefix; breaking changes are announced before they ship. Current dataset size is on
/api/version (ingredient_count) and in the data_quality block on every scoring
response.
What changed (Nov 2026)
Plans and limits were reorganised. If you call the API from your own code, read Authentication and Rate limits again.
- Without a subscription (anonymous, or signed in on a free account): still 120 requests a minute, and now also 250 API calls a day per address, 2,000 per rolling 30 days per address, and 1,000 a day per network range (an IPv4 /24 or an IPv6 /48, shared by every address in it). Daily counts reset at midnight UTC.
- Website plans (Pro monthly and yearly, Educator, press pass): 120 requests a
minute, down from 300, 300 calls a day and 3,000 a month, down from 10,000.
These plans cover the compkitchen.com website. An API key on one of them is refused
with
402. - Developer plan (new): programmatic access with an
X-API-Keyat 600 requests a minute, 3,000 calls a day and 10,000 a month. Issued by email. - Contract plans (enterprise, platform, embed, design partner) have no daily or monthly ceiling from us; the allowance is in the contract.
- Bulk copying is now acted on automatically. A caller requesting an unusually large number of distinct records gets shortened lists, and an anonymous address or range that keeps doing it is suspended for a day. See Rate limits.
The one thing to read before anything else
Every endpoint's score means something different. They are not comparable, and averaging across them is meaningless. This is the most common way to misuse this API.
| Endpoint | The number | What it actually is |
|---|---|---|
/api/pair |
final_score |
50% compound overlap + 50% recipe co-occurrence + a synergy term, plus bonuses |
/api/pair-score, /api/basket |
final_score |
the same pairing score as /api/pair, for exactly the pairs you name |
/api/pair with 2 ingredients |
final_score |
the mean of the candidate's two pair scores |
/api/pair with 3+ ingredients |
final_score |
the candidate's weakest pair score by default, or the mean with aggregate=avg |
/api/bridge |
score |
the mean of two pair scores, after a usefulness filter |
/api/sub |
final_score |
Jaccard similarity of compound sets. Not the pairing formula |
/api/formula-sub |
score |
how much of what the formula loses a candidate restores, minus a drift penalty |
/api/mood |
final_score |
geometric mean of descriptor-match intensity and proportion. recipe_score is N/A |
/api/pantry |
score |
three different meanings in one response — see that endpoint |
/api/compare |
jaccard |
raw set overlap. No pairing formula involved at all |
Where a result carries scoring_mode, it names which of these applies. Read it.
A ranked list is not a scoring table. /api/pair and /api/batch return the top of
a ranking, so a pair that is not in the list comes back absent, not as a low score.
Never render an absent pair as 0%. To score exactly the pairs you have in mind, use
/api/pair-score (one pair) or /api/basket (every pair in a set, one call). Neither
ranks, so nothing can hide a pair from them.
/api/pair values are /api/pair values. The Python engine.pair() method returns
different numbers for the same ingredients — different defaults, different
post-processing. Never compare a figure from one interface against the other.
Reading a score
Scores are not percentages. final_score runs from 0 to 1, but its meaning is its
rank among all ingredient pairs, and that distribution sits low. In classic scoring the
median random pair scores about 0.11 and the 99th percentile about 0.69; in
science scoring the median is about 0.09. So 0.45 is not "45% good" — it is above the
large majority of pairs. Showing a bare score as a percentage invites exactly the wrong
reading.
What to show instead:
percentile—/api/pair-scoreand every pair in/api/basketcarrypercentile: where this score falls among random ingredient pairs, 0 to 100, for the scoring formula you asked for./api/pair-scoreaddspercentile_note, which quotes the median and 99th percentile from the same table.percentileisnullwhen the table is unavailable; we do not guess one. Ranked results from/api/pairdo not carry it./api/score-guide?ingredient=— percentiles of one ingredient's own candidates (p10top99, plusbest). "Top decile for apple" is a claim the data supports; "0.7 is good" is not. There is no validated absolute cut-off.
Do not present pairing_strength or confidence as a verdict on a pairing.
pairing_strength(strong/moderate/weak) is computed from the compound score alone (0.60 and 0.30 are the cut-offs). It ignores recipe evidence, so a classic kitchen pairing can readweak.confidence(high/medium/low, reasons inconfidence_factors) says how much to trust the number given our data: how many compounds are shared, how thin the thinner profile is, whether the shared compounds are near-universal, whether the profiles are FlavorDB's shared default, and — inclassicscoring only — how many recipes use the pair (five or fewer caps it atmedium, none caps it atlow). It is a data-quality band, not a quality rating.
final_score is not a weighted average of compound_score and recipe_score and
can exceed both. In classic scoring it is 0.50·compound + 0.50·recipe +
0.20·√(compound·recipe), plus aroma, chef, taste, method and external-pairing bonuses,
capped at 1.0. A classic pair with no recipe co-occurrence and a compound score above
0.10 is scored against a recipe floor of 0.05 while its reported recipe_score stays 0.0;
such rows carry recipe_floor_applied: true. scoring=science is 70% compound overlap
and 30% aroma similarity with the same bonuses and no recipe term. /api/score-guide
publishes the formula with every response.
measured_score is the conservative one. final_score includes bonuses derived by a
language model from chef pairings and aroma families; measured_score keeps only compound
overlap, recipe co-occurrence, synergy, cooking method and the external pairing signal.
profile_basis says whether a compound profile is a measurement: measured,
template (most of it is FlavorDB's shared default set) or duplicate (identical to
another ingredient's). Two template ingredients overlap almost completely because both
sides are the default, and their score describes the default, not the food.
Authentication
Send your key in the X-API-Key header. There is no Authorization: Bearer form and
no query-string parameter.
curl -H "X-API-Key: $COMPKITCHEN_KEY" \
"https://compkitchen.com/api/pair?ingredients=strawberry"
Keys come with the developer plan and the contract plans (enterprise, platform,
embed, design partner, classroom, and staff grants). Email [email protected] to set
one up. Your key is on /account.
A valid key on a website plan is refused. Pro (monthly and yearly), Educator and the
press pass cover the website, not programmatic access. A key belonging to one of those
accounts gets 402 on every /api/* path except /api/health, /api/whoami and
/api/version, before any session cookie is consulted:
{"detail": "This subscription includes the compkitchen.com website, not programmatic API access. API keys are issued on the developer and enterprise plans — email [email protected] and we will sort it out.",
"plan": "monthly", "website_access": "unaffected"}
An invalid key does not error. If the header is missing or the key matches no active
paid account, the request falls through to the browser session cookie and, failing that,
is treated as having no subscription. Check is_pro in the response rather than assuming,
or call /api/whoami.
is_pro reports your entitlement. It does not flip when a response is briefly
throttled: a throttled reply carries rate_limited: true and a reason, keeps every
count exact, and only shortens the name lists.
Rate limits
Four ceilings apply, checked in this order after a suspension check (see Bulk copying below). A refused call stops at the first one it hits.
1. Per minute (sliding 60-second window):
| Caller | Limit | Counted per |
|---|---|---|
| No subscription (anonymous or free account) | 120 / min | address |
| Website plan, signed in | 120 / min | account |
Developer or contract plan via X-API-Key |
600 / min | key |
Exceeding it returns 429 with {"detail": "Rate limit exceeded."}. The per-minute
counters are kept per server process, so treat the figures as approximate: a burst can be
admitted somewhat above the nominal number, and the window resets on deploy. Do not build
logic that expects the 429 at exactly N.
2. Per day and per 30 days, without a subscription. Counted per address (an IPv4 address, or an IPv6 /64):
| Ceiling | Limit | 429 body field |
Retry-After |
|---|---|---|---|
| per address, per day | 250 | daily_limit |
seconds to midnight UTC |
| per address, rolling 30 days | 2,000 | monthly_limit |
86400 |
| per network range (IPv4 /24, IPv6 /48), per day | 1,000 | network_daily_limit |
seconds to midnight UTC |
{"detail": "Daily limit reached (250 API calls a day without a subscription). It resets at midnight UTC. For more, see compkitchen.com/pricing or email [email protected].",
"daily_limit": 250}
3. Per day, with a subscription. Counted per account; the 429 carries
daily_limit and a Retry-After to midnight UTC.
| Plan | Calls a day |
|---|---|
| Website plans (Pro, Educator, press pass) | 300 |
| Developer, classroom and staff grants | 3,000 |
| Contract plans (enterprise, platform, embed, design partner) | no daily ceiling |
4. Per calendar month, with a subscription.
| Plan | Calls a month |
|---|---|
| Website plans | 3,000 |
| Developer and staff grants | 10,000 |
| Classroom | 30,000 |
| Contract plans | agreed in the contract |
Exhausting it returns a different 429 with quota_monthly, used_this_month and a
Retry-After in seconds to the start of the next UTC month. Retrying will not clear it;
the fix is a conversation. Calls a signed-in website session makes to /api/* (every run
on /tools and /compare) count against the same allowance as the account's key.
/api/health, /api/whoami and /api/version never count against the daily or monthly
limits (the per-minute limit applies to every request). A
/api/basket call is charged one unit per 25 pairs returned (minimum one), so a
25-ingredient basket (300 pairs) costs 12.
The client address is taken from CF-Connecting-IP, so requests are limited per real
caller and not per Cloudflare edge.
Bulk copying. Separately from volume, we watch how many distinct records (ingredient profiles, compound records, taste and evidence records, pair scores) one caller requests, over the last hour and over 30 days. Past that point:
- the caller gets free-tier depth on list fields — counts stay exact, lists are
shortened, and the response says
rate_limited: truewith areason; - an address or network range without a subscription is suspended from the API for a day;
- a website-plan account is suspended from the API for a day on the second occurrence within seven days;
- developer and contract accounts are never suspended automatically; we get in touch.
A suspended caller gets 403 with suspended_until and "website_access":
"unaffected" — pages still load. If you think a suspension is a mistake, email
[email protected].
Some older material quotes 60/min. That figure belongs to a standalone app that is not what serves compkitchen.com.
Free vs Pro
"Pro" below means any active paid plan, whichever way it authenticates (website session or key). Callers without one get the top 5 results in full, then locked stubs.
is_pro is present on every gated response. Key off is_pro, not off the presence of
the other fields. On result-list endpoints the free tier adds truncated: true,
free_limit, total_count and locked_count; Pro carries truncated: false and omits
the other three. Endpoints that gate compound LISTS instead (below) add truncated,
free_list_limit and upgrade. Responses with no result list (/api/profile,
/api/score-guide, /api/pair-score) carry only truncated: false.
A locked stub carries only:
{ "ingredient": "elderberry", "category": "fruit-berry", "novelty_tier": "common",
"shared_compound_count": 267, "is_novel": false, "is_expert": false, "locked": true }
Free callers also lose compound_details on the results they can see — the
per-compound threshold and OAV panel is Pro-only.
Which endpoints gate their compound LISTS. /api/compare, /api/compound and
/api/info truncate compound-name lists for free callers; the COUNTS are always exact, so
a short list is never a short profile.
Paid only (402 without an active paid plan): /api/basket, /api/batch,
/api/reformulate-cost, /api/taste-profile, /api/pair-evidence and the CSV exports.
From your own code, that means a developer or contract key.
data_quality
Present on most scoring responses (values abbreviated):
"data_quality": {
"ingredient_count": 861,
"recipe_count": 612557,
"flavordb_source": "...",
"recipe_source": "...",
"scoring_revision": "2026-10-15.1",
"dataset_fingerprint": "5039562c89db"
}
recipe_count is the number of browsable recipes (the /recipes database), not the
co-occurrence corpus that scores are computed from; the two are different artifacts and
move independently. scoring_revision and dataset_fingerprint are the change signals —
see Detecting a change below.
A further key, warning, appears if and only if the engine is running on embedded
fallback data instead of the real corpus. Test for its presence, not for a key count.
If you see warning, do not trust the scores.
Errors
Three shapes, all real:
{"detail": "At most 25 ingredients allowed."} // 422, flat string
{"detail": [{"type": "missing", "loc": ["query", "ingredients"],
"msg": "Field required", "input": null}]} // 422, validation
{"detail": "Ingredient(s) not found in graph: ['notarealfood']",
"suggestions": ["nutmeg", "..."]} // 404, with suggestions
A 404 answers two different questions, and keeps them apart. suggestions is a
spelling question — did you mean broccoli. For some ingredients we are asked for
and do not hold, the response also carries related and related_note: a food
question, "we do not have that, here is what we do have near it". Every related row
carries a why. These are neighbours, not substitutions — none of them are wired into
ingredient resolution, so asking for one still returns 404 rather than quietly scoring
something else.
| Code | When |
|---|---|
402 |
a paid-only endpoint without an active paid plan; or any /api/* call with a key on a website plan |
403 |
API access for this address, range or account is suspended (suspended_until) |
404 |
ingredient not in the graph — includes suggestions, sometimes related |
405 |
wrong method |
422 |
validation: missing, too many, empty, out of range, bad enum |
429 |
a rate limit or quota — the body names which (see Rate limits) |
503 |
engine still loading after a deploy — retry shortly |
Limits are checked before your input is validated, so an over-limit caller gets 429
even for a malformed request. Otherwise malformed input gets 422 before the engine is
consulted, so you see 422 rather than 503 during a warm-up.
Input sanitising: NFKC normalise → lowercase → strip → drop every character outside
[a-z0-9 -] → reject if empty or over 60 characters. So Crème Fraîche becomes
crme frache and will 404. Send plain ASCII names.
Caching
Results are cached server-side for 6 hours, and the cache holds the ungated result with gating applied per request — a Pro-computed body can never reach a free caller through it. A deploy clears it.
Responses carry Cache-Control: public, max-age=60, s-maxage=300, except Pro responses,
which use private, max-age=60. /api/version, /api/whoami, every 429 and 403, and
/api/reformulate-cost are no-store.
Endpoints
GET /api/pair
Arity selects the mode. This is the least obvious thing about the API:
ingredients |
Mode | Question answered |
|---|---|---|
| 1 | top_pairings |
what goes with this? |
1, with rank=familiar or rank=jaccard |
familiar / jaccard |
what do cooks actually put with this? |
| 2 | bridge |
what goes with both? (mean of the two pair scores) |
| 3+ | gap |
what fits this set? (weakest pair by default) |
| Param | Default | Notes |
|---|---|---|
ingredients |
required | comma-separated, max 25, normalised and deduplicated. An ingredient we cannot score is SKIPPED, not fatal — see below |
top_n |
10 |
1–100 |
scoring |
classic |
or science (70% compound + 30% aroma similarity, no recipe term) |
diet |
— | vegan, vegetarian, no-dairy, no-nuts, no-gluten, kosher, halal, no-eggs, no-alcohol. Unknown values are silently ignored |
cuisine |
— | applies only under classic; unknown values silently ignored |
cooking |
— | e.g. grilled; valid values from /api/cooking-states. Forces scoring=science. Single ingredient only |
measured |
0 |
1 ranks on measured_score (the formula without language-model bonuses). Single ingredient only |
diversify |
1 |
0 turns OFF the category cap — see Absence is not a zero |
aggregate |
min |
3+ ingredients only: min ranks a candidate on its WEAKEST pair with your set, avg on the mean |
bridge_rank |
avg |
2 ingredients only: weakest orders candidates by the weaker of their two pair scores, so a near-twin of one input cannot win; each row keeps its mean final_score |
rank |
score |
familiar or jaccard re-rank on what cooks actually do — single ingredient only, see below. Anything else is treated as score |
exclude_similar |
0 |
1 drops candidates that are chemical near-substitutes for the input — single ingredient, rank=score only |
exclude_substitutes |
0 |
1 drops candidates labelled relationship: "substitute" — narrower than exclude_similar |
patch_final_score |
— | recipe_score: see When a zero means "unknown" |
cooking, measured and exclude_similar act on a single ingredient ranked by score;
diversify on one ingredient and on 3+; cuisine under classic on every mode except
familiar / jaccard. The query block echoes what was performed, not what was
requested: scoring, cooking_state, measured_only, rank, diversify, aggregate
and bridge_rank report what ran, and applied_note / rank_note /
exclude_similar_note say when something you asked for did not apply. diet and
cuisine are not echoed.
curl "https://compkitchen.com/api/pair?ingredients=strawberry&top_n=5"
Response, abbreviated (values from an earlier revision, shown for shape):
{"query": {"ingredients": ["strawberry"], "scored": ["strawberry"], "unrecognised": [],
"top_n": 5, "scoring": "classic", "rank": "score", "diversify": true, "...": "..."},
"mode": "top_pairings", "count": 5,
"truncation": {"candidates_scored": "...", "returned": 5, "withheld": "...", "top_n_max": 100,
"note": "This is a RANKED SLICE, not a scoring table. ..."},
"results": [{"ingredient": "kiwifruit", "final_score": 0.7802, "measured_score": 0.5742,
"compound_score": 0.2711, "recipe_score": 0.7027, "confidence": "high",
"relationship": "complement", "...": "..."}],
"is_pro": false, "truncated": false, "data_quality": {"...": "..."}}
Absence is not a zero
A pair missing from this list has not scored 0. Three things keep a well-scoring candidate out of the list, and none of them is the score:
- The cut.
top_nis at most 100.truncation.withheldsays how many scored candidates were left out. - The category cap. With
diversify=1(the default) each food group gets at mostmax(2, min(3, top_n // 4))places — at the defaulttop_n=10that is two vegetables however well a third scores.diversify=0turns it off. It applies to one ingredient and to 3+ (gap); two-ingredientbridgemode has no cap. - The duplicate-profile filter. A candidate whose compound profile overlaps your
input's by more than 90% is dropped as a duplicated record rather than a pairing.
Nothing disables this one,
diversify=0included.
To score exactly the pairs you name, use /api/pair-score or /api/basket. Neither
ranks, so no filter can hide a row — and an unscoreable pair comes back
final_score: null with a reason, never 0.0.
rank=familiar — the obvious answer instead of the interesting one
The default ranking is built on compound overlap plus NPMI, and NPMI measures how SURPRISING a co-occurrence is, not how common. A ubiquitous partner such as cream co-occurs with strawberry thousands of times and still looks unremarkable to the maths; a rare one with a few dozen co-occurrences looks striking. That is the point of the engine, but it is not what a shopper expects.
&rank=familiar re-ranks on real co-occurrence, damped for ubiquity, with ingredients
that are present because a recipe is a recipe removed (salt, flour, sugar, egg, water,
butter, milk, oil and a few more). &rank=jaccard ranks on recipe overlap divided by
recipe union, which is harsher still on common partners.
Scores are identical across the three rankings — the same scoring applied to whichever
rows a ranking selects; scoring_revision does not move. But they are not the same
rows reordered: each ranks the whole candidate space by its own criterion, so the lists
differ substantially. mode tells you which one ran. Both apply to a single ingredient;
on a basket the response comes back with rank: "score" and a rank_note. The excluded
base list is a judgement — butter is on it, so lemon + butter will not appear in a
familiar list, though it scores normally everywhere else.
Substitute or complement
Every result carries relationship, either "complement" or "substitute". A pair is
labelled substitute when it is chemically alike and both sit in a food group where
only one can fill the slot — protein, dairy, grain, bakery, egg, beverage, fungus. A dish
takes as many spices as you like, so two alike spices stay complements.
substitute means "could stand in for", NOT "do not combine". Beef and pork are
interchangeable and classic together. Read the label beside recipe_cooccurrence in the
same row: a substitute with thousands of co-occurrences is a real combination.
relationship does not change any score and does not filter anything unless you pass
&exclude_substitutes=1; the removed names come back in query.excluded_as_substitute.
/api/pair-score and /api/basket carry the field too. Every row of /api/sub is
labelled substitute, since that is what the endpoint is for.
An ingredient we don't have does not sink the request
If one of your ingredients is unrecognised, the rest are still scored:
| Field | Meaning |
|---|---|
query.ingredients |
what you asked for, after normalisation |
query.scored |
what actually took part |
query.unrecognised |
the names that were dropped |
query.resolved, query.substitutions |
what each input resolved to (olive oil → olive) |
Watch mode. Dropping an ingredient changes the arity, and arity selects the mode —
three ingredients minus one unknown is a two-ingredient question, so the response says
bridge, not gap. If NOTHING is recognisable you get a 404 naming the failing words.
Multi-ingredient responses
Two and three ingredients answer different questions. Two ingredients rank on the
mean of the candidate's two pair scores; three or more rank on the weakest pair unless
you pass aggregate=avg. If you want one consistent "how good is the basket on average"
question at every size, send aggregate=avg — and diversify=0 too, since
aggregate=avg alone is still category-capped. For "what should I add to this basket" in
one call, two-ingredient bridge mode applies neither the category cap nor the
duplicate-profile filter.
With two or more ingredients, every row carries the numbers behind its aggregate:
| Field | Meaning |
|---|---|
per_input |
the candidate's score against each input separately, with compound_score and recipe_score |
query.aggregate |
which rule was actually PERFORMED — avg or min. Echoed from behaviour, not from your request |
basket_internal |
the pairs among your own ingredients, scored once per request |
basket_average (per row) |
the mean of every pair in the basket adding this candidate would produce |
{"basket_internal": [{"a": "tomato", "b": "basil", "final_score": 0.7356}],
"results": [{"ingredient": "oregano", "final_score": 0.7999, "basket_average": 0.7785,
"per_input": [{"ingredient": "tomato", "final_score": 0.7243},
{"ingredient": "basil", "final_score": 0.8755}]}]}
(Abbreviated; values from an earlier revision.) basket_internal is an empty list for a
single ingredient. basket_average is computed from the published four-decimal scores,
so adding up the rows printed beside it reproduces it. Without a Pro key,
basket_internal is returned for baskets of up to 4 ingredients; above that it is empty,
basket_internal_locked is true, and rows carry no basket_average.
/api/batch counts one request per ingredient against your monthly quota.
GET /api/pair-score
The score for exactly one pair, regardless of how either ranks for the other. Rank is asymmetric — a pair can be 7th from one side and 134th from the other — but the score is symmetric, and this returns it.
| Param | Default | Notes |
|---|---|---|
a, b |
required | the two ingredients |
scoring |
classic |
or science |
Returns final_score, compound_score, recipe_score, percentile,
percentile_note, shared_compound_count, recipe_cooccurrence, relationship,
confidence, pairing_strength, why_it_pairs, profile_basis,
query_profile_basis, the coverage counts (compound_count, query_compound_count,
coverage_compound_count), profile_sizes, profile_information, resolved and
substitutions, and data_quality. Unknown ingredient → 404.
POST /api/basket
Every pairwise score in a basket, in one call: n(n−1)/2 scores, no ranking, no cap, no filters. Paid only.
Body: {"ingredients": [...], "scoring": "classic"} — 2 to 25 ingredients
(300 pairs), scoring classic or science. Inputs are cleaned and deduplicated in your
order; non-string or invalid entries are dropped.
curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
-d '{"ingredients": ["pasta", "cherry tomato", "parmesan cheese"]}' \
https://compkitchen.com/api/basket
Each entry in pairs carries a, b, resolved, final_score, compound_score,
recipe_score, shared_compound_count, recipe_cooccurrence, relationship,
confidence, pairing_strength and percentile. summary gives pair_count,
scored_pair_count, unscored_pair_count, average_score, min_score, max_score,
strongest_pair and weakest_pair. query carries substitutions, unresolved,
profile_sizes and profile_information.
A pair that cannot be scored returns final_score: null, never 0.0, with
unscored_reason — ingredient_not_found, same_ingredient (two words for one
ingredient) or scoring_error — and unscored_detail. Zero is a real score meaning "no
relationship"; unknown is not zero. Average over pairs where final_score is not null;
summary already does.
GET /api/novel
Same scoring as /api/pair, filtered to pairs that are chemically compatible but rarely
cooked together — compound ≥ 0.20 and recipe ≤ 0.15 by default. The engine relaxes
those thresholds when too few pairs qualify, so rows below the nominal cut-off are
expected. Takes ingredient (singular), top_n (default 10, 1–100) and diet.
GET /api/sub
final_score is Jaccard similarity of compound sets, not the pairing formula. It
answers "what most resembles this ingredient", which is not the same as "what can I use
instead" — it has no notion of function, texture or quantity.
| Param | Default | Notes |
|---|---|---|
ingredient |
required | |
top_n |
10 |
1–100 |
diet |
— | as /api/pair |
exclude |
— | allergen groups: tree-nuts, peanuts, nuts, dairy, egg, soy, gluten, fish, shellfish, sesame, coconut (common spellings such as nut, lactose, crustacean, soya, nut-free accepted) |
same_role |
on | only candidates that do the same job in a dish (sweetener, fat, binder, acid, allium, … or else the same food group), ordered by job_fit: half compound similarity, half how alike the two ingredients' recipe company is. On by default since 2026-11-12; same_role=0 returns the compound-only list in compound order. Filters and orders rows; never changes a row's score |
exclude fails closed: an ingredient with no dietary classification is excluded too,
and an unrecognised group returns 422 naming the valid ones.
GET /api/formula-sub
Replacing one member of a formula, in context of the rest. A near-identical candidate scores low when the outgoing ingredient's chemistry is already covered by its neighbours, because the formula never lost it.
| Param | Notes |
|---|---|
formula |
required, comma-separated, max 25, including the one being replaced |
replace |
required, which member to swap out |
top_n |
default 10, 1–100 |
diet, exclude |
same vocabulary as /api/sub |
Depth-gated: free callers get the first rows in full and a truncated remainder.
Read thin_evidence before you read score. When only one or two compounds separate
the outgoing ingredient from the rest of the formula, high scores are noise. n_lost
says how many compounds are at stake; n_supplied_by_rest how many the neighbours
already cover. n_lost: 0 is a finding, not an error. weak_evidence means the
ingredient has no distinctive chemistry on record anywhere. The score key is score,
not final_score.
POST /api/reformulate-cost (paid only, no-store) ranks the same candidates and puts
your own costs beside the flavour ranking as a second axis — no price term enters any
score, and a candidate we cannot price is kept, with its cost fields null. Email us for
the body format.
GET /api/mood
Ingredients matching a descriptor (smoky, bright, cozy), passed as descriptor or
mood; top_n (default 10, 1–100) and diet as elsewhere. final_score is a geometric
mean of how many of the ingredient's compounds match and how strongly. recipe_score
is N/A here and scoring_mode is mood.
Matching is substring-on-compound-name, not chemical identity. Multi-word descriptors
must be space-separated: every character outside a-z, 0-9, space and hyphen is
deleted, so smoky/sweet becomes smokysweet.
GET /api/pantry
What you can make from what you have. ingredients (comma-separated), top_n (default
5, 1–20), diet. Three different score meanings in one response:
combos[].score— the standard pairing scoretrios[]— three-way analysisbuy_next[]— ranked by how many new good pairings the addition unlocks, a breadth measure, not a pairing score. When the pantry holds a meat or fish, other meats and fish are listed after the sides (since 2026-11-12); nothing is removed
Partial failure is silent. An unrecognised ingredient is dropped as long as at least
one input resolves; the pantry field is the authoritative list of what was scored.
combos and trios need a graph edge between members, so a one-ingredient pantry
returns both empty while buy_next is still populated.
GET /api/compare
Side-by-side compound sets for two ingredients, a and b. jaccard is raw set
overlap — no pairing formula. The arrays (shared, a_only, b_only) are truncated for
free callers; the counts (shared_count, a_only_count, b_only_count) and jaccard
are always exact, so use the counts, not the array lengths. For three or more
ingredients, use the page: /compare?ing=a&ing=b&ing=c.
GET /api/bridge
The third ingredient connecting a and b. score is the mean of the two pairing
scores. You get up to six; top_n is not exposed. Results are filtered for usefulness
rather than purely by score: same-category siblings of either input and drinks are
dropped. If nothing survives, the response is 404 with "No bridge found for those
two." — the same status as an unknown ingredient, so read detail. For an unfiltered
two-ingredient ranking, use /api/pair with two ingredients.
GET /api/compound/{name}
Full record for one compound: odour description, threshold, aroma family, chemical class,
CAS, PubChem CID, formula, molecular weight, volatility, and which foods carry it. The food
list (ingredients, food_oavs) is Pro and capped for free callers; ingredient_count
is always complete. /api/compound-lookup?q= resolves a CAS number, PubChem CID or FEMA
number to the compound.
GET /api/taste-profile
Paid only. Two taste answers for one ingredient, side by side and never blended:
estimated (the profile the engine uses — model-assigned labels blended with USDA
nutrient-derived values, seven tastes on 0–1) and measured (amounts of taste-active
compounds as printed in open-access paper tables, matched by PubChem CID, with paper
ids; see measured_note). A known ingredient with no measurements returns 200 with
"measured": null and a measured_reason. Null is unknown, not zero; inside
measured, a taste with no measured compound is listed under tastes_not_measured.
Mass (µg/kg) and volume (µg/L) concentrations are kept separate, never pooled.
GET /api/pair-evidence
Paid only. What open-access paper tables measured for the compounds two ingredients (a,
b) share — the amount and the paper's own odour activity value in each food, with
PMC ids. limit 1–50, default 15. Reporting only: it never feeds a score. Compounds found
above threshold in both foods come first (odor_active: "both", "one" or null). The
same ingredient twice → 422. Every null is unknown, not zero. Amounts are µg/kg;
values printed per litre are read at density 1.
GET /api/version
What is running, so you can detect a change instead of noticing it: scoring_revision,
dataset_fingerprint, changelog (an array of {revision, summary}, newest first),
ingredient_count and a note. Served no-store, never counted against a limit, and
safe to poll. Returns 503 while a deploy warms up.
Lookup endpoints
| Endpoint | Returns |
|---|---|
GET /api/info?ingredient= |
category, compound count, recipe count; the compound list and top connections are truncated for free callers |
GET /api/profile?ingredient= |
aroma categories and chemical classes for one ingredient (top_aroma, aroma_distribution) |
GET /api/score-guide?ingredient=&scoring= |
percentiles of that ingredient's own candidates — see Reading a score |
GET /api/ingredients |
every ingredient name in the graph |
GET /api/cooking-states?ingredient= |
valid cooking values for that ingredient |
GET /api/recipes/search?q= |
browsable recipe search; limit 1–100 (default 24), offset |
GET /api/health |
{"status": "ok" \| "degraded", "engine_ready": bool} — degraded adds enrichment_failed |
GET /api/whoami |
{"signed_in": bool, "is_premium": bool} — check your key works |
GET /api/health // during a deploy warm-up
{"status": "ok", "engine_ready": false}
engine_ready: false means a deploy is warming; scoring requests will 503 until it
flips. engine_ready: true means the engine loaded, not that every data source did:
status: "degraded" with an enrichment_failed list means some enrichment is missing and
scores may be affected — alert on status, not only on engine_ready.
Pro-only: batch and export
POST /api/batch — top pairings for up to 50 ingredients in one request (counted before
de-duplication). Body: ingredients (list), top_n (default 5, 1–50), scoring
(classic | science). Results are keyed by the normalised name; an ingredient we do
not hold maps to null with a 200, and non-string or invalid entries are dropped. Each
list is a ranked slice exactly like /api/pair — category-capped and filtered — so use
/api/basket when you need specific pairs.
curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
-d '{"ingredients": ["strawberry", "garlic"], "top_n": 3}' \
https://compkitchen.com/api/batch
GET /api/export/pair.csv, sub.csv, mood.csv, compare.csv — the JSON endpoints'
parameters, returned as CSV (pair.csv defaults to top_n=30). compare.csv is
long-format and returns the complete shared / A-only / B-only lists.
Without an active paid plan these return 402:
{"detail": "Batch pairings need a developer plan with an API key. Email [email protected] and we will set you up."} // /api/batch
{"detail": "Basket scoring needs a developer plan with an API key. Email [email protected] and we will set you up."} // /api/basket
{"detail": "CSV export requires a Pro subscription. Upgrade at /account."} // /api/export/*
What the API knows: /api/ingredients?include=
The default response is {"ingredients": [...]}. Two additions are opt-in.
include=aliases returns the static alias table, filtered to aliases whose target is
a scorable ingredient. custard apple scores as apple; if you adjust scores client-side
using our compound counts you need the RESOLVED name. It is not the whole of resolution —
plurals, prefixes and suffix probing also resolve inputs — so for the authoritative answer
read query.resolved on the response.
include=corpus_only lists terms that appear in the recipe corpus but reach no
scorable ingredient, with recipe counts and a reason:
{"term": "lard", "recipes": 12760, "reason": "no_compound_data"}
{"term": "soup", "recipes": 10348, "reason": "excluded"}
excluded means it is a category or a dish and never will be an ingredient.
no_compound_data means it is a food we hold no chemistry for.
When a zero means "unknown": patch_final_score
compound_score: 0.0 reports two opposite facts identically — these share nothing, and
we hold very few compounds for this ingredient. The second is a statement about our
coverage, and because final_score carries half its weight on the compound score it costs
the pair roughly half its score.
profile_sizes is how many compounds we hold for each ingredient you asked about
(each result row's compound_count is the partner's). profile_information adds how
many of those compounds actually discriminate — informative counts compounds carried by
at most half of all ingredients, and informative_share is null rather than 0.0 when
unavailable. Where to find them:
| Endpoint | Where |
|---|---|
/api/pair |
query.profile_sizes, query.profile_information |
/api/basket |
query.profile_sizes, query.profile_information |
/api/pair-score |
top level — this response has no query block |
patch_final_score=recipe_score does the adjustment server-side on /api/pair: when
the thinner of the two profiles is below 25 compounds — the same cut-off confidence uses
— final_score becomes the recipe score alone. It applies before top_n is selected,
so it changes which rows appear, not just their order. Patched rows carry
score_basis: "recipe_only" and final_score_blended with the original value;
query.patched_rows counts them. Off by default, and pairs where both profiles are full
are never touched.
Every per_input entry and every basket_internal pair carries compound_score and
recipe_score beside final_score, so you can compute your own adjustment. When you
recompute final_score from them, apply the recipe floor: under classic, recipe_score
0 with compound_score above 0.10 means use 0.05.
Detecting a change: watch both signals
Every scoring response carries data_quality, and /api/version carries the same two
fields plus the changelog. Neither is sufficient on its own.
| field | moves when | set by |
|---|---|---|
scoring_revision |
anything moves published scores — a formula change or a data change | by hand, in the same release as the change |
dataset_fingerprint |
the size of what is loaded changes | derived at request time from the loaded data |
dataset_fingerprint is a 12-character digest of counts and labels: ingredient and
compound counts, the browsable recipe count, the co-occurrence index's recipe and pair
totals, and the source strings. It does not move for a data change that leaves those
counts alone, and it can move with no score change at all.
So treat scoring_revision as the score signal, and read changelog on
/api/version for what each revision changed. If you cache our scores, key the cache on
scoring_revision (adding the fingerprint is harmless and catches a mis-loaded
deployment). /api/version is served no-store, so it is safe to poll.
Honest limits
Publishing these because you will hit them, and finding out from your own results is worse than being told.
Measured concentration is thin. Which molecules are present is broad; at what
concentration covers a small share of the compound vocabulary. Anything OAV-derived
inherits that ceiling. A pair can score well on shared compounds present in both foods
far below their odour thresholds — chemically real, perceptually irrelevant.
measured_score and confidence are the honest signals.
Recipe co-occurrence carries a Western bias. The corpus is largely English-language,
so combinations common in cuisines it under-represents score lower on the recipe half
than they deserve. scoring=science drops the recipe term entirely.
Substitution is chemical, not culinary. /api/sub can offer peach for butter — they
share lactones. It knows nothing about fat content, structure or heat behaviour.
Some profiles are defaults, not measurements. Ingredients with profile_basis:
"template" carry FlavorDB's shared default set, and many others are characterised only by
common metabolites. They pair plausibly with everything and specifically with nothing;
/api/formula-sub reports this as weak_evidence.
Support
[email protected]. If a score looks wrong, send the exact request URL — every
score is reproducible from its inputs, and we would rather find out.
Something look wrong? Send the exact request URL to [email protected] — every score is reproducible from its inputs.