> This page is for Developer Documentation. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.benchling.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.benchling.com/_mcp/server. # Batch update ProcedureRunPlan PATCH https://{tenant_name}.benchling.com/api/v3/procedure-run-plan:batch-update Content-Type: application/json Batch update ProcedureRunPlan synchronously in one transaction. Maximum 25 items per request. Reference: https://docs.benchling.com/docs/api/benchling-api/procedure-run-plan/batchupdate ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Headers - `EARLY-ACCESS` (string, optional) — Set to true to access beta operations via /api/v3. ### Body (application/json) This endpoint expects an object. - `items` (list of UpdateProcedureRunPlanInputWithPathParams, required) ## Response ### 200 OK - `items` (list of ProcedureRunPlan, required) ## Errors ### 400 Procedure Run Plan Batch Update Request Bad Request Error Bad Request - `detail` (GeneralErrorDetail, required, nullable) - `instance` (string, required) - `status` (integer, required) - `title` (string, required, nullable) - `type` (string, required) - `invalidId` (string, optional) ### 403 Procedure Run Plan Batch Update Request Forbidden Error Forbidden - `detail` (GeneralErrorDetail, required, nullable) - `instance` (string, required) - `status` (integer, required) - `title` (string, required, nullable) - `type` (string, required) - `invalidId` (string, optional) ### 404 Procedure Run Plan Batch Update Request Not Found Error Not Found - `detail` (GeneralErrorDetail, required, nullable) - `instance` (string, required) - `status` (integer, required) - `title` (string, required, nullable) - `type` (string, required) - `invalidId` (string, optional) ### 409 Procedure Run Plan Batch Update Request Conflict Error Conflict - `detail` (GeneralErrorDetail, required, nullable) - `instance` (string, required) - `status` (integer, required) - `title` (string, required, nullable) - `type` (string, required) - `invalidId` (string, optional) ### 429 Procedure Run Plan Batch Update Request Too Many Requests Error Too Many Requests - `detail` (TooManyRequestsErrorBodyDetail, required, nullable) - `instance` (string, required) - `status` (integer, required) - `title` (string, required, nullable) - `type` (string, required) - `invalidId` (string, optional) ### 500 Procedure Run Plan Batch Update Request Internal Server Error Internal Server Error - `detail` (InternalServerErrorBodyDetail, required, nullable) - `instance` (string, required) - `status` (integer, required) - `title` (string, required, nullable) - `type` (string, required) - `errorId` (string, optional) ## Types ### UpdateProcedureRunPlanInputWithPathParams - `id` (string, required) - `conditionOrder` (list of ConditionOrderForPmdvInput, optional) — Reorder existing conditions per procedure method definition version (PMDV). For each PMDV included, **all** existing condition IDs for that PMDV in the plan must be present exactly once. The order of IDs in `conditionIds` determines the new display positions (0-indexed). - `confirmationMethodByParamVersionId` (list of ConfirmationMethodByParamVersionIdInput, optional) — Replace the confirmation method overrides for specific procedure parameters. Pass an empty array to clear all overrides. When `workflowFlowchartConfigVersionId` changes to a different version, omitting this field clears all existing overrides automatically, since parameter version IDs are specific to a procedure version and may be invalid for the new one. - `dataEntryMode` (enum, optional) — Controls how data entry worksheets are created upon promotion. `INDIVIDUAL_CONDITION_REPLICATES` creates one worksheet per condition-replicate. `ALL_CONDITION_REPLICATES_TOGETHER` creates a single shared worksheet (not supported for assay run plans). - Allowed values: `INDIVIDUAL_CONDITION_REPLICATES`, `ALL_CONDITION_REPLICATES_TOGETHER` - `description` (string, optional) — A human-readable description of the run plan. Must not exceed 255 characters. - `workflowFlowchartConfigVersionId` (string, optional, nullable) — The ID of the workflow flowchart config version to switch to. Format: `wffccv_XXXXXXXX`. When changed and planning-time split-pool isn't enabled, the plan's whole condition set is rebuilt from scratch to keep uniform per-method coverage: every existing condition is deleted, and a fresh condition is created for each method of the new flowchart, one per prior canonical position (matching name, description, and replicate count). When planning-time split-pool is enabled, an existing condition whose method isn't a node of the new flowchart is instead reassociated with the new flowchart's method version for the same underlying method, if one exists, or deleted if no matching method exists. In both cases, planned parameter, material input, and equipment values, as well as planned unit operation links, are cleared, since they can't be preserved across the change. Set to null to clear the linked procedure flowchart version. When switching to a genuinely different procedure version (one with a different ID than the currently linked version), any existing `confirmationMethodByParamVersionId` overrides are automatically cleared unless `confirmationMethodByParamVersionId` is also provided in the same request. ### ProcedureRunPlan A draft experiment plan that can be promoted to a `ProcedureRun` for execution. Scientists use run plans to configure experimental conditions, parameter values, and replicates before starting an actual experiment. Belongs to a `Study` and exposes its Workflows-backed procedure template through `procedureFlowchartConfigVersion`. Contains `ProcedureRunPlanCondition` objects that define the different experimental configurations to test. The `dataEntryMode` (see `ProcedureRunDataEntryMode`) specifies whether each condition-replicate will have its own data entry worksheet or share a single worksheet. The `confirmationMethodByParamVersionId` allows overriding default confirmation methods for specific parameters. Upon promotion, the run plan becomes a `ProcedureRun` with corresponding `ProcedureRunCondition` and `ProcedureRunConditionReplicate` objects. Also known as a "draft experiment" in the Benchling UI. ## Product mapping - `ProcedureRunPlan` is the API model for the **draft procedure run** setup object in the UI. - Promoting a run plan creates the executable `ProcedureRun` and carries forward its condition/replicate setup. - `__typename` (string, optional) - `confirmationMethodByParamVersionId` (list of ConfirmationMethodByParamVersionId, optional) - `createdAt` (string, optional) - `creator` (PrincipalRef, optional) - `dataEntryMode` (enum, optional) - Allowed values: `INDIVIDUAL_CONDITION_REPLICATES`, `ALL_CONDITION_REPLICATES_TOGETHER` - `description` (string, optional) - `id` (string, optional) - `modifiedAt` (string, optional) - `procedureFlowchartConfigVersion` (ProcedureFlowchartConfigVersionRef, optional, nullable) - `procedureRun` (ProcedureRunRef, optional, nullable) - `procedureRunPlanConditions` (string, optional) - `study` (StudyRef, optional) ### GeneralErrorDetail ### TooManyRequestsErrorBodyDetail ### InternalServerErrorBodyDetail ### ConditionOrderForPmdvInput - `conditionIds` (list of string, required) - `templateMethodVersionId` (string, required) ### ConfirmationMethodByParamVersionIdInput - `confirmationMethod` (enum, required) - Allowed values: `TABLE`, `PLATE_MAP` - `paramVersionId` (string, required) ### ConfirmationMethodByParamVersionId Associates a procedure parameter version with its confirmation method, keyed by the parameter version ID. Used in `ProcedureRunPlan` to look up how a specific version of a parameter's values should be confirmed—either via TABLE (structured table entry) or PLATE_MAP (plate-based layout). - `__typename` (string, optional) - `confirmationMethod` (enum, optional) - Allowed values: `TABLE`, `PLATE_MAP` - `paramVersionId` (string, optional) ### PrincipalRef - `__typename` (string, optional) - `id` (string, optional) ### ProcedureFlowchartConfigVersionRef - `__typename` (string, optional) - `id` (string, optional) ### ProcedureRunRef - `__typename` (string, optional) - `id` (string, optional) ### StudyRef - `__typename` (string, optional) - `id` (string, optional) ## Examples **Request** ```json { "items": [ { "id": "prp_Xk9mLpQr", "conditionOrder": [ { "conditionIds": [ "prpc_Bm7nWsKt", "prpc_Zq2rPvJx" ], "templateMethodVersionId": "pcmdv_Hn5kRtYw" } ], "confirmationMethodByParamVersionId": [ { "confirmationMethod": "TABLE", "paramVersionId": "schver_Rm4nTvWz" } ], "dataEntryMode": "INDIVIDUAL_CONDITION_REPLICATES", "description": "Updated dose-response plan", "workflowFlowchartConfigVersionId": "wffccv_Lk3mQpXn" } ] } ``` **Response** ```json { "items": [ { "__typename": "__typename", "confirmationMethodByParamVersionId": [ {} ], "createdAt": "createdAt", "dataEntryMode": "INDIVIDUAL_CONDITION_REPLICATES", "description": "description", "id": "id", "modifiedAt": "modifiedAt", "procedureRunPlanConditions": "procedureRunPlanConditions" } ] } ``` **SDK Code** ```python import requests url = "https://{tenant_name}.benchling.com/api/v3/procedure-run-plan:batch-update" payload = { "items": [ { "id": "prp_Xk9mLpQr", "conditionOrder": [ { "conditionIds": ["prpc_Bm7nWsKt", "prpc_Zq2rPvJx"], "templateMethodVersionId": "pcmdv_Hn5kRtYw" } ], "confirmationMethodByParamVersionId": [ { "confirmationMethod": "TABLE", "paramVersionId": "schver_Rm4nTvWz" } ], "dataEntryMode": "INDIVIDUAL_CONDITION_REPLICATES", "description": "Updated dose-response plan", "workflowFlowchartConfigVersionId": "wffccv_Lk3mQpXn" } ] } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.patch(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://{tenant_name}.benchling.com/api/v3/procedure-run-plan:batch-update'; const options = { method: 'PATCH', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"items":[{"id":"prp_Xk9mLpQr","conditionOrder":[{"conditionIds":["prpc_Bm7nWsKt","prpc_Zq2rPvJx"],"templateMethodVersionId":"pcmdv_Hn5kRtYw"}],"confirmationMethodByParamVersionId":[{"confirmationMethod":"TABLE","paramVersionId":"schver_Rm4nTvWz"}],"dataEntryMode":"INDIVIDUAL_CONDITION_REPLICATES","description":"Updated dose-response plan","workflowFlowchartConfigVersionId":"wffccv_Lk3mQpXn"}]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ```