Your recipe. Your method.

Start simply

Use exact ingredient IDs and the current catalogVersion from GET /api/v2/ingredients. Save the following as recipe.json, replacing the catalog placeholder. Quantities below are an illustrative API example, not a qualified beverage formula.

{
  "source": "ingredients",
  "name": "Strawberry-lime trial",
  "catalogVersion": "<current catalogVersion>",
  "batchMassG": 500,
  "ingredients": [
    {"ingredientId":"flavor.strawberry","sourceMassG":0.5},
    {"ingredientId":"flavor.lime","sourceMassG":0.2},
    {"ingredientId":"acid.citric","sourceMassG":0.3},
    {"ingredientId":"sweet.sucrose","sourceMassG":10},
    {"ingredientId":"base.water","sourceMassG":489}
  ],
  "preparation": {
    "steps": [
      "Dissolve the citric acid and sucrose in the recipe water.",
      "Stir in the strawberry and lime source products.",
      "Inspect for undissolved material or separation and record observations."
    ],
    "notes": "Keep the exact formula and this preparation sequence."
  }
}

This recipe explicitly specifies 489 g water; all ingredients total 500 g. When water is supplied, the API preserves every quantity and requires the total to equal batchMassG. To calculate water automatically instead, omit the base.water line. The returned order includes the calculated amount. Quantities are grams of the exact commercial source products; the order freezes their identities. carbonated defaults to false and replicates to 1.

curl --fail-with-body \
  https://labs.deconfound.com/api/v2/lab-orders \
  -H "X-Deconfound-Api-Key: $DECONFOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: strawberry-lime-method-001" \
  --data-binary @recipe.json

Requires orders:write; reading the ingredient bank requires ingredients:read. See authentication for the two credentials. This is a single order-creation call, with no AI generation call.

The response is 201 {"order":{…}}. It includes your frozen preparation, balanced ingredients, and worksheet.steps. Private bench records are API-only; they do not appear in the customer-order admin dashboard. Read GET /api/v2/lab-orders/{id}/worksheet with the owner’s orders:read key to see readiness holds and the next step for each batch, and GET /api/v2/lab-orders/{id}/results for recorded evidence. The /lab?order=<order.id> link preserves your ID and shows the API handoff.

How text instructions work

Text steps remain in your order. Setup and final sampling records surround them. The operator weighs and records each ingredient and lot as it is added, using bench notes where needed. After the text steps, the worksheet asks for those recorded totals. These are record-only steps; ingredients are not added again.

Text is preserved rather than interpreted into machine controls. It does not override the recipe’s quantities. The lab reviewer resolves contradictions, verifies the method and records actual equipment and lots before starting. Use structured steps when you want the API to check allocation, timing or temperature explicitly.

Add structure where it matters

Replace preparation.steps with typed steps to control addition order, split the water, and set process targets. This example uses the same formula above:

"preparation": {
  "steps": [
    {"type":"add","ingredientId":"base.water","massG":300,
     "instruction":"Add the first water portion."},
    {"type":"add","ingredientId":"acid.citric",
     "instruction":"Add the recipe citric acid."},
    {"type":"add","ingredientId":"sweet.sucrose",
     "instruction":"Add the recipe sucrose."},
    {"type":"mix","temperatureC":20,"durationSeconds":60,
     "instruction":"Stir to dissolve; record appearance."},
    {"type":"add","ingredientId":"flavor.strawberry",
     "instruction":"Add strawberry."},
    {"type":"add","ingredientId":"flavor.lime",
     "instruction":"Add lime."},
    {"type":"add","ingredientId":"base.water","massG":189,
     "instruction":"Add the remaining water allowance."},
    {"type":"mix","temperatureC":20,"durationSeconds":90,
     "instruction":"Mix the complete batch and inspect."},
    {"type":"chill","temperatureC":4,"durationSeconds":300,
     "instruction":"Condition using the reviewed chilling method."}
  ]
}

These process conditions are example inputs, not validated instructions. Once any typed add is present, the steps must allocate every ingredient, including specified or calculated water, exactly in aggregate. Omitted massG means that ingredient’s full recipe quantity. Split additions use explicit portions. Missing, excess, unknown or duplicate full additions are rejected before the order is saved.

Every typed step may also have a short title. Structured targets override the corresponding bench defaults. The API evaluates recorded time and temperature against each step’s target. Source quantities stay fixed; changing equipment settings never reorders your method or alters ingredient amounts.

If there are no typed additions, the worksheet uses the manual protocol and subsequent record-only ingredient totals. A requested carbonation without a typed step receives a final record-only confirmation, not a second carbonation operation. Typed additions use unique step IDs; split actual masses are summed and all step-level lots are retained.

Include the bench setup in the same request

Optionally add a complete benchSettings object alongside preparation. It prepopulates the method review, so you do not need a separate configure call. Use actual, verified equipment values. The following shows the shape only:

"benchSettings": {
  "balanceId": "<actual balance ID>",
  "minimumWeighableMassG": 0.001,
  "vessel": "<actual vessel and usable capacity>",
  "mixer": "<actual mixing equipment>",
  "mixingMethod": "<reviewed method and setting>",
  "mixingSeconds": 60,
  "temperatureC": 20,
  "temperatureToleranceC": 1,
  "massTolerancePercent": 1,
  "samplingMethod": "<reviewed sampling procedure>",
  "holdInstructions": "<reviewed conditions and disposition>",
  "chillMethod": "<reviewed chilling equipment and method>"
}

Numbers above are illustrative. Omit the object if the bench is not yet known; missing settings become visible holds. Partial objects are rejected. Each mix/chill step needs targets either inline or from the bench defaults. For chilling defaults, use chillTemperatureC and chillSeconds. Carbonation requires carbonationEquipment and carbonationProcedure.

Supplied settings are unreviewed proposals. The order remains pending_review. A lab-authorized operator reviews the exact formula, method, products, lots and equipment, then accepts and starts it. The balance minimum is checked against each planned portion, including split additions. Manual text methods require review of any portions described only in text.

You can include tests and replicates in the same request. Defaults record pH, apparent Brix and recovered mass with no pass/fail targets. Physical execution, purchasing and instrument automation are not connected.

Validation and changes

Preparation supports 1–30 ordered steps. Instructions are 1–1,500 characters, optional titles 1–100, and notes up to 2,000. Step masses are positive grams with at most four decimals. Mix temperature is 0–60 °C; chill temperature 0–25 °C; duration is 1–86,400 whole seconds. These are software input limits, not validated operating ranges. Unknown fields and operation types are rejected.

Replay a lost response using the same body and key. Instructions and settings are included in the request identity. Create a new order to change the formula or preparation. configure may change settings before execution while retaining your method; it invalidates approval. No methods or quantities change after starting. Recorded mistakes use the existing audited clerical-correction workflow.

Custom preparation and inline setup currently apply to source:"ingredients". Orders from an AI idea or saved Studio generation preserve that saved formulation and cannot accept replacement methods or ingredients in their creation payload.