xPlantAPI
API referenceMedia

Update a media recipe

Changes only the fields you send. Only the recipe's creator can change it.

PATCH/api/v1/media-recipes/{id}
Scope write:media_recipes
Open in ChatGPTOpen in ClaudeView .md

A change to the formulation — the title, notes, components, pH or preparation notes — records a new version and raises version. Earlier versions are kept, and records already linked to the recipe keep the version they were linked to. Changing status, visibility or is_public does not create a version.

components replaces the whole list, so send every component to keep, with its id.

Path parameters

NameTypeRequiredDescription
idstring (uuid)YesThe record's id.

Request body

FieldTypeRequiredDescription
titlestringNoThe recipe's name. 1–200 characters.
componentsobject[]NoThe complete ingredient list. It replaces the current one, so send every component to keep, with its id. Up to 100 items.
components[].idstringNoYour id for this component. Kept as given; when left out, one is assigned and returned, so an update can send it back. 1–64 characters.
components[].namestringYesThe ingredient, for example Sucrose or 6-BAP. 1–200 characters.
components[].qtystringYesThe amount as the recipe writes it, for example 30 or 0.5. 1–50 characters.
components[].unitstringNoThe unit of qty, for example g/L or mg/L. 1–20 characters.
components[].concentrationstringNoA concentration, when the recipe states one apart from the amount. 1–50 characters.
notesstring | nullNoFree-text notes, up to 500 characters. null clears them. Up to 500 characters.
status"active" | "archived" | "deprecated" | "draft" | "published"NoOne of active, archived, deprecated, draft, published.
visibility"private" | "team"NoWho in the workspace can see the recipe. private: only the key's owner, who is recorded as its creator. team: everyone in the workspace.
is_publicbooleanNoPublish the recipe to xPlant's public recipe library, where anyone can read it. A draft recipe stays out of the library either way.
ph_targetnumber | nullNoTarget pH, 0 to 14. Stored to two decimal places. null clears it. From 0 to 14.
sterilization_notesstring | nullNoHow to sterilize the medium, up to 500 characters. Up to 500 characters.
storage_notesstring | nullNoHow to store the prepared medium, up to 500 characters. Up to 500 characters.
usage_notesstring | nullNoHow to use the medium, up to 500 characters. Up to 500 characters.

Example

curl -X PATCH https://app.xplantpro.com/api/v1/media-recipes/4b6d8f0a-2c4e-4d6f-8a0c-2e4b6d8f0a2c \
  -H "Authorization: Bearer $XPLANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "MS + 0.5 mg/L BAP",
    "components": [
      {
        "id": "c1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b",
        "name": "MS basal salts",
        "qty": "4.4",
        "unit": "g/L"
      },
      {
        "id": "d2b3c4d5-e6f7-4a81-9b0c-1d2e3f4a5b6c",
        "name": "Sucrose",
        "qty": "30",
        "unit": "g/L"
      },
      {
        "id": "e3c4d5e6-f7a8-4b92-8c1d-2e3f4a5b6c7d",
        "name": "6-BAP",
        "qty": "0.5",
        "unit": "mg/L"
      },
      {
        "id": "f4d5e6f7-a8b9-4ca3-9d2e-3f4a5b6c7d8e",
        "name": "Agar",
        "qty": "7",
        "unit": "g/L"
      }
    ]
  }'

Response

200 with { "ok": true, "data": … }. data holds the result.

FieldTypeRequiredDescription
idstring (uuid)Yes—
titlestringYes—
statusstring | nullYesOne of active, archived, deprecated, draft, published.
originstring | nullYesWhere the recipe came from, for example user or imported.
visibilitystringYesprivate: only its creator can see it. team: everyone in the workspace can.
is_publicbooleanYesPublished to xPlant's public recipe library.
notesstring | nullYes—
ph_targetnumber | nullYesTarget pH.
sterilization_notesstring | nullYes—
storage_notesstring | nullYes—
usage_notesstring | nullYes—
componentsobject[]YesThe ingredients, in order.
components[].idstringYesThe component's id. Send it back in an update to keep the component.
components[].namestringYesThe ingredient.
components[].qtystringYesThe amount as the recipe writes it.
components[].unitstring | nullYesThe unit of qty.
components[].concentrationstring | nullYesA concentration, when the recipe states one apart from the amount.
versionintegerYesThe recipe's version. It goes up by one each time the formulation changes, and every version is kept.
created_bystringYesUser id of the workspace member who created the recipe. Only they can change it.
created_atstring | nullYesISO 8601.
Response
{
  "ok": true,
  "data": {
    "id": "a3d5f7b9-1c2e-4f6a-8b0d-2e4f6a8c0e1f",
    "title": "MS + 0.5 mg/L BAP",
    "status": "active",
    "origin": "user",
    "visibility": "team",
    "is_public": false,
    "notes": "Shoot multiplication medium for aroid cultures.",
    "ph_target": 5.8,
    "sterilization_notes": "Autoclave for 20 minutes at 121 °C.",
    "storage_notes": "Keep poured vessels at 4 °C and use within two weeks.",
    "usage_notes": null,
    "components": [
      {
        "id": "c1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b",
        "name": "MS basal salts",
        "qty": "4.4",
        "unit": "g/L",
        "concentration": null
      },
      {
        "id": "d2b3c4d5-e6f7-4a81-9b0c-1d2e3f4a5b6c",
        "name": "Sucrose",
        "qty": "30",
        "unit": "g/L",
        "concentration": null
      },
      {
        "id": "e3c4d5e6-f7a8-4b92-8c1d-2e3f4a5b6c7d",
        "name": "6-BAP",
        "qty": "0.5",
        "unit": "mg/L",
        "concentration": null
      },
      {
        "id": "f4d5e6f7-a8b9-4ca3-9d2e-3f4a5b6c7d8e",
        "name": "Agar",
        "qty": "7",
        "unit": "g/L",
        "concentration": null
      }
    ],
    "version": 2,
    "created_by": "0d7e4b9a-6f21-4c3e-8a5b-2e9f1c7d4a60",
    "created_at": "2026-09-25T14:12:03.000Z"
  }
}
Response headerMeaning
X-Request-IdIdentifies this request. Include it when you contact support.

Errors

StatusCodeWhen
400VALIDATION_ERRORThe request body is not valid JSON.
401UNAUTHORIZEDThe key is missing, malformed or revoked, or its owner is no longer a member of the workspace.
402PAID_PLAN_REQUIREDThe workspace's plan does not include the API. The full API is included with xPlant+ Teams and Enterprise; on Hobby and Pro Lab, keys can connect devices only.
403FORBIDDENThe key lacks a scope this operation requires, or its owner's current role in the workspace cannot use it — a key never does more than its owner can in xPlant. error names the scope, and for a role, the role it needs.
403DEVICE_TOKEN_NOT_ACCEPTEDA device token was sent; this operation needs a workspace API key.
403MEDIA_RECIPE_NOT_OWNERThe key's owner can see the recipe but did not create it. Only a recipe's creator can change it.
404NOT_FOUNDNo recipe with this id is visible to the key's owner in the workspace: it does not exist there, or it is another member's private recipe.
422VALIDATION_ERRORA field failed validation. error names the first one, for example title: title is required.
429RATE_LIMIT_EXCEEDEDToo many requests for this key, device token or workspace. Wait Retry-After seconds.
500MEDIA_RECIPE_UPDATE_FAILEDThe change could not be saved. Retry later.

Branch on code, never on the error text. See Errors.

Get a media recipe

One recipe with its components and current version.

Start an SOP run

Starts a run of an SOP: the record that a procedure was carried out, step by step, against the version the lab had in force.

On this page

Path parametersRequest bodyExampleResponseErrors