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 & Beauty
home-careHome Care
beverageBeverages
supplementDietary Supplements
foodFood & Snacks
sauces-condimentsSauces & Condiments
color-cosmeticsColor Cosmetics
fragranceFragrance & Perfumery
alcoholic-beverageAlcoholic Beverages
pet-groomingPet Grooming
pet-supplementPet Supplements
deodorantDeodorant & Antiperspirant
sunscreenSunscreen
candleCandles (Wax Products)
intimate-careIntimate / Feminine Care

Hair, 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

id

This version's id. Read it, cost it or change it with this id.

product_id

The product. Every version of it shares this id.

version

1 for the first formula, and one more for each change.

name, category, product_type, created_at

The product's name and the brief's category and product type; when this version was made.

ingredients[].inci_name

The label name (INCI), or the ingredient's own name where it has none.

ingredients[].common_name

The everyday name, or null.

ingredients[].percentage

Its share of the whole formula by weight. The rows add up to 100.

ingredients[].phase

The phase the method adds it in, named as the formula names it ("Water Phase", "Cool-Down Phase"), or null.

ingredients[].function

What it does in the formula, or null.

instructions

The method, step by step. Left out with ?format=concise, as are the fields below.

texture, estimated_ph, shelf_life

Estimates from the formula, not measurements. A sample and stability testing confirm them.

key_benefits

What the formula is built to do, as a list.

regulatory_notes

What 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 /formulas

Start a formula from a brief. Answers with a job.

POST /formulas/{id}/revisions

Start 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 /formulas

Your formulas, newest first. ?limit= up to 100 (20 if left out), and ?cursor= with the next_cursor of the page before.

GET /formulas/{id}/cost

What 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 /credits

The 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 unauthenticated

No key was sent. Send it in the Authorization header.

401 invalid_key

The key is not one of yours, or it was turned off.

403 access_closed

The API is not open on the account right now. Its keys are kept.

403 insufficient_scope

The key may not make this call.

400 invalid_request

A field is missing, unknown or out of range. The message names it.

400 idempotency_key_required

A call that starts a formula needs an Idempotency-Key header.

422 idempotency_key_reused

That key was used for a different request. Send a new one.

409 request_in_progress

The first call with that key is still running. Try again in a few seconds.

409 product_busy

A version of that product is being written. Send the change when its job is ready.

409 product_on_order

The product is on an order. Change it in Genie, where the team working on the order sees the change.

409 outcome_unknown

An earlier call with that key never reported back. Check your formulas, then send a new key if nothing was started.

402 credits_needed

The account does not have the credits a formula takes. Nothing was started.

429 daily_limit

The account has started as many formulas as one day allows.

429 rate_limited

Too many calls on the key. Retry-After says how long to wait.

404 not_found

No formula, product or job of yours has that id.

503 not_started

It did not start, and nothing was charged. Try again.

500 internal

Something 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_..." }
    }
  }
}
Genie API and MCP server | Genie