Skip to main content

API reference

CompKitchen JSON API

Endpoints, authentication, rate limits, and what every score actually means.

On this page
  1. What changed (Nov 2026)
  2. The one thing to read before anything else
  3. Reading a score
  4. Authentication
  5. Rate limits
  6. Free vs Pro
  7. data_quality
  8. Errors
  9. Caching
  10. Endpoints
  11. GET /api/pair
  12. GET /api/pair-score
  13. POST /api/basket
  14. GET /api/novel
  15. GET /api/sub
  16. GET /api/formula-sub
  17. GET /api/mood
  18. GET /api/pantry
  19. GET /api/compare
  20. GET /api/bridge
  21. GET /api/compound/{name}
  22. GET /api/taste-profile
  23. GET /api/pair-evidence
  24. GET /api/version
  25. Lookup endpoints
  26. Pro-only: batch and export
  27. What the API knows: /api/ingredients?include=
  28. When a zero means "unknown": patch_final_score
  29. Detecting a change: watch both signals
  30. Honest limits
  31. Support

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-Key at 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-score and every pair in /api/basket carry percentile: where this score falls among random ingredient pairs, 0 to 100, for the scoring formula you asked for. /api/pair-score adds percentile_note, which quotes the median and 99th percentile from the same table. percentile is null when the table is unavailable; we do not guess one. Ranked results from /api/pair do not carry it.
  • /api/score-guide?ingredient= — percentiles of one ingredient's own candidates (p10 to p99, plus best). "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 read weak.
  • confidence (high / medium / low, reasons in confidence_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 — in classic scoring only — how many recipes use the pair (five or fewer caps it at medium, none caps it at low). 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: true with a reason;
  • 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_n is at most 100. truncation.withheld says how many scored candidates were left out.
  • The category cap. With diversify=1 (the default) each food group gets at most max(2, min(3, top_n // 4)) places — at the default top_n=10 that is two vegetables however well a third scores. diversify=0 turns it off. It applies to one ingredient and to 3+ (gap); two-ingredient bridge mode 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=0 included.

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 score
  • trios[] — three-way analysis
  • buy_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.