Genie API and MCP
Everything Genie does with a formula, from your own code or from an assistant: start one from a brief, change it in words, read every ingredient and its exact percentage, and see what its ingredients cost.
Everything a call does is done as the account that made the key, on its credits. A formula takes one to four minutes to write, so a call that starts one answers at once with a job to follow.
Before the first call
Every call goes to this address, with your key in the Authorization header. Bodies and answers are JSON.
https://www.madebygenie.com/api/v1
Authorization: Bearer gk_live_...Make a formula
Send a brief. Only category and product_type are needed; the rest steers the formula. Send an Idempotency-Key with it, any unique text such as a UUID: if the call times out, send it again with the same key and you get the first answer, with nothing started or charged twice.
curl -X POST https://www.madebygenie.com/api/v1/formulas \
-H "Authorization: Bearer $GENIE_API_KEY" \
-H "Idempotency-Key: 5b0c8a52-7c1f-4d6e-9a0b-0d3c2f1e4a77" \
-H "Content-Type: application/json" \
-d '{
"category": "skincare-beauty",
"product_type": "gel moisturizer",
"name": "Cloud Gel",
"primary_benefit": "lightweight daily hydration for oily skin",
"key_ingredients": ["niacinamide", "sodium hyaluronate"],
"avoid_ingredients": ["fragrance"],
"container": "50 ml airless pump",
"targets": ["pH 5.0 to 5.5"]
}'The fields: category, product_type, name, primary_benefit, key_ingredients and avoid_ingredients (up to 20 each), reference_products and targets (up to 8 each), texture, container, target_audience. An unknown field is refused by name.
The categories:
skincare-beautySkincare & Beautyhome-careHome CarebeverageBeveragessupplementDietary SupplementsfoodFood & Snackssauces-condimentsSauces & Condimentscolor-cosmeticsColor CosmeticsfragranceFragrance & Perfumeryalcoholic-beverageAlcoholic Beveragespet-groomingPet Groomingpet-supplementPet SupplementsdeodorantDeodorant & AntiperspirantsunscreenSunscreencandleCandles (Wax Products)intimate-careIntimate / Feminine CareHair, body and skin care are written under skincare-beauty, a CBD topical under skincare-beauty and a CBD ingestible under supplement. An unknown category is refused with this list.
The answer is a job. Ask about it every five to ten seconds until it is ready, then read the formula it names.
202
{ "job": { "id": "9f2c...", "kind": "formula", "status": "queued",
"product_id": "c41a...", "formula_id": null },
"credits_remaining": 380 }
curl https://www.madebygenie.com/api/v1/jobs/9f2c... -H "Authorization: Bearer $GENIE_API_KEY"
{ "job": { "id": "9f2c...", "status": "ready", "formula_id": "7be0...", ... } }
curl https://www.madebygenie.com/api/v1/formulas/7be0... -H "Authorization: Bearer $GENIE_API_KEY"
{ "id": "7be0...", "product_id": "c41a...", "version": 1, "name": "Cloud Gel",
"ingredients": [
{ "inci_name": "Aqua", "percentage": 84.6, "phase": "Water Phase", "function": "solvent" },
{ "inci_name": "Niacinamide", "percentage": 4, "phase": "Water Phase", "function": "active" }
],
"instructions": "...", "estimated_ph": 5.2, "shelf_life": "24 months" }What a formula carries
idThis version's id. Read it, cost it or change it with this id.
product_idThe product. Every version of it shares this id.
version1 for the first formula, and one more for each change.
name, category, product_type, created_atThe product's name and the brief's category and product type; when this version was made.
ingredients[].inci_nameThe label name (INCI), or the ingredient's own name where it has none.
ingredients[].common_nameThe everyday name, or null.
ingredients[].percentageIts share of the whole formula by weight. The rows add up to 100.
ingredients[].phaseThe phase the method adds it in, named as the formula names it ("Water Phase", "Cool-Down Phase"), or null.
ingredients[].functionWhat it does in the formula, or null.
instructionsThe method, step by step. Left out with ?format=concise, as are the fields below.
texture, estimated_ph, shelf_lifeEstimates from the formula, not measurements. A sample and stability testing confirm them.
key_benefitsWhat the formula is built to do, as a list.
regulatory_notesWhat the formula was written to meet for its category and markets, and what is left for you to check, as text. A starting point, not a sign-off.
Change a formula
Say the change in words, up to 4,000 characters, and name the newest version of the product: a change is always made to that one, and an older id is refused with the id of the newest. The answer is a job, followed the same way. One version of a product is written at a time.
curl -X POST https://www.madebygenie.com/api/v1/formulas/7be0.../revisions \
-H "Authorization: Bearer $GENIE_API_KEY" \
-H "Idempotency-Key: 0c9d1b7e-2f3a-4e5b-8c6d-7a8b9c0d1e2f" \
-H "Content-Type: application/json" \
-d '{ "instructions": "Swap the glycerin for propanediol and bring the pH to 5." }'Every call
POST /formulasStart a formula from a brief. Answers with a job.
POST /formulas/{id}/revisionsStart a new version of a product from a change in words. {id} is the product's newest version. Answers with a job. Earlier versions are kept.
GET /jobs/{id}Where a job stands: queued, running, ready (with formula_id) or failed (with reason).
GET /formulas/{id}A formula with every ingredient and its exact percentage. Add ?format=concise to leave out the method and notes.
GET /formulasYour formulas, newest first. ?limit= up to 100 (20 if left out), and ?cursor= with the next_cursor of the page before.
GET /formulas/{id}/costWhat the ingredients cost per kilogram, at mid-volume prices on file. Per unit only when the formula records its fill size; otherwise multiply the per-kilogram figure by your fill. rough is true, with no figures, when too few of its ingredients are priced. Ingredients only.
GET /creditsThe credits left, the free formulas left this month and the day they come back. All null while the account's use is not counted (an account from before the new terms, until they take effect).
A key may make 120 reads and 20 writes a minute.
When a call is refused
A refusal is one shape, with a code your program can act on and a message that says what to do.
{ "error": { "code": "product_busy", "message": "...", "retry_after": 30 } }401 unauthenticatedNo key was sent. Send it in the Authorization header.
401 invalid_keyThe key is not one of yours, or it was turned off.
403 access_closedThe API is not open on the account right now. Its keys are kept.
403 insufficient_scopeThe key may not make this call.
400 invalid_requestA field is missing, unknown or out of range. The message names it.
400 idempotency_key_requiredA call that starts a formula needs an Idempotency-Key header.
422 idempotency_key_reusedThat key was used for a different request. Send a new one.
409 request_in_progressThe first call with that key is still running. Try again in a few seconds.
409 product_busyA version of that product is being written. Send the change when its job is ready.
409 product_on_orderThe product is on an order. Change it in Genie, where the team working on the order sees the change.
409 outcome_unknownAn earlier call with that key never reported back. Check your formulas, then send a new key if nothing was started.
402 credits_neededThe account does not have the credits a formula takes. Nothing was started.
429 daily_limitThe account has started as many formulas as one day allows.
429 rate_limitedToo many calls on the key. Retry-After says how long to wait.
404 not_foundNo formula, product or job of yours has that id.
503 not_startedIt did not start, and nothing was charged. Try again.
500 internalSomething failed on the Genie side. Try again.
Your formulas and your data
The formulas you make are yours. Genie claims no ownership of them, takes no license back and charges no royalty. They are not used to train public AI models, and Genie's AI providers may not train on them; Genie may use anonymized, aggregated data and chemist corrections to improve its own formulation systems.
Send only briefs and formulas you have the right to share: a client's or an employer's confidential formula does not belong here. The Terms say it in full.
Connect an assistant
Genie is also an MCP server, at https://www.madebygenie.com/api/mcp, with seven tools: create_formula, revise_formula, get_formula_job, get_formula, list_formulas, get_formula_cost and get_credit_balance.
In the Claude or ChatGPT app, add Genie as a custom connector with that address, and sign in to Genie when it asks. You choose what it may do, and you can disconnect it from your account at any time.
A tool that takes a server address and a key, such as Claude Code or Cursor, uses one of your keys:
{
"mcpServers": {
"genie": {
"type": "http",
"url": "https://www.madebygenie.com/api/mcp",
"headers": { "Authorization": "Bearer gk_live_..." }
}
}
}