--- title: "Update Study" method: PATCH path: "/api/v3/study/{study_id}" tags: ["Study"] --- # Update Study `PATCH /api/v3/study/{study_id}` ## Request - Base URL: `https://{tenant_name}.benchling.com` - URL: `https://{tenant_name}.benchling.com/api/v3/study/{study_id}` - Auth: HTTP bearer Update a study. Omit any field to leave it unchanged. ## Editable fields `name`, `description`, `folderId`, and `schemaFields` can be updated. Keys in `schemaFields` must be field system names or field API IDs. ## phase - See the `phase` field for the full list of allowed lifecycle values. - Study types that skip the design phase cannot be set to `DESIGN`. - Moving from `DESIGN` to `EXECUTION` requires an approved study design when the schema requires design approval. ## designEntryId and designEntry - `designEntryId` is only supported for custom studies. Omit to leave the design entry unchanged, or pass `null` to remove it. - On a custom study in `EXECUTION` under a schema that requires design approval, `designEntryId` cannot change unless the same update also moves the study into `DESIGN`. - Use `designEntry` to create a new entry and set it as the design entry in one request. It cannot be combined with `designEntryId`. ## displayId - Only allowed when the study schema's `idGenerationMode` is `MANUAL`. Providing `displayId` for an auto-generating schema fails validation. - When provided, must be unique within the tenant. - Omitting `displayId` leaves the current value unchanged. ## authorIds - Omit to leave existing authors unchanged. - Provide an array of user or app IDs to replace the current author list. - Pass an empty array to clear all authors. - Do not pass `null`. ## Archiving - To archive, set `archived` to `true` and provide `archiveReason`. - To unarchive, set `archived` to `false`. ## Path parameters - `study_id` string, required ## Request body - UpdateStudyInput - `archiveReason` string: Why it is being archived. Required when `archived` is `true`, and not allowed when unarchiving. - `archived` boolean: Set to `true` to archive or `false` to unarchive it. Archiving requires `archiveReason`. - `authorIds` string[]: The IDs of the users or apps to set as study authors. Omit to leave authors unchanged. Pass an empty array to clear all authors. - `description` string: The description of the study. Omit to leave unchanged. Max 2048 characters. - `designEntry` CreateStudyDesignEntryInput - `folderId` string, required - `initialDay` string - `name` string, required - `schemaFields` object - `schemaId` string: The ID of the schema to associate with this object. - `templateId` string - `designEntryId` string, nullable: The ID of an entry to use as the study design entry. Omit to leave unchanged. Pass null to remove the design entry. Only supported for custom studies. On a custom study in EXECUTION under a schema that requires design approval, this cannot be changed unless the update also moves the study into the DESIGN phase. - `displayId` string: The ID to assign to the study. Only allowed when the study schema is configured for manual ID assignment (i.e., `idGenerationMode` is `MANUAL`). Must be unique within the tenant. - `fieldValues` UpdateFieldValueInput[]: Use schemaFields instead. - `fieldDefinitionId` string, required - `value` unknown, required - `folderId` string: The ID of the folder to move the study to. Omit to leave unchanged. - `name` string: The name of the study. Omit to leave unchanged. - `phase` 'DESIGN' | 'EXECUTION' | 'COMPLETE': The lifecycle phase of the study. Omit to leave unchanged. See the endpoint description for transition rules. - `schemaFields` object ## Response `200` OK - Study: A structured unit used to plan and organize research in Benchling. Each study progresses through phases (see `StudyPhase`) sequentially from design to execution to completion. The current phase determines what modifications are permitted on the study and its associated data. - `__typename` string - `archiveDatetime` string, datetime, nullable: No longer supported. - `archiveReason` string, nullable - `archiveUser` PrincipalRef - `__typename` string - `id` string, api_id - `archived` boolean - `authors` string, uri, nullable: Users and apps designated as authors of the study. - `createdAt` string, datetime, nullable - `creator` PrincipalRef - `__typename` string - `id` string, api_id - `description` string, nullable - `designEntry` EntryRef - `__typename` string - `id` string, api_id - `displayId` string, nullable: Human-readable identifier for the study. For schemas with auto-generated IDs, assigned by the server at creation. For MANUAL schemas, may be set at creation or update. - `folder` FolderRef - `__typename` string - `id` string, api_id - `id` string - `modifiedAt` string, datetime, nullable - `name` string - `phase` 'DESIGN' | 'EXECUTION' | 'COMPLETE' - `schema` StudySchemaRef - `__typename` string - `id` string, api_id - `schemaFields` SchemaFieldValue[], nullable - `__typename` string - `fieldDefinition` SchemaFieldDefinitionRef - `__typename` string - `id` string, api_id - `id` string - `linkedEntityId` string, nullable - `value` union: Types of values that Benchling can interpret. - object: A type that represents a list of BenchlingValues, used for multi-value cells (e.g. alias columns). - `__typename` 'ArrayValue', required: Discriminator value: ArrayValue - `value` SingularBenchlingValue[] - union: A union of value types that can appear as elements within an ArrayValue. Identical to BenchlingValue but excludes ArrayValue to prevent nesting. Keep in sync with BenchlingValue. - object: A type that represents boolean values. - … - object: A type that represents datetime values. - … - object: A type that represents date values. - … - object: A type that represents decimal value as strings. - … - object: A type that represents integer values. - … - object: A type that represents JSON values. - … - object: A type that represents a list of links to other objects. - … - object: A type that represents links to other objects. - … - object: A type that represents text (string) values with an associated URL. - … - object: A type that represents text (string) values. - … - object: A type that represents boolean values. - `__typename` 'BooleanValue', required: Discriminator value: BooleanValue - `value` boolean: The boolean value. - object: A type that represents datetime values. - `__typename` 'DateTimeValue', required: Discriminator value: DateTimeValue - `value` string, datetime: The datetime value with UTC as the timezone. - object: A type that represents date values. - `__typename` 'DateValue', required: Discriminator value: DateValue - `value` string, date: The date value. - object: A type that represents decimal value as strings. - `__typename` 'DecimalValue', required: Discriminator value: DecimalValue - `numericValue` number, double, nullable: Deprecated. The float representation of the decimal value. - `value` string, nullable: The decimal value in a string representation - object: A type that represents integer values. - `__typename` 'IntegerValue', required: Discriminator value: IntegerValue - `value` integer: The integer value. - object: A type that represents JSON values. - `__typename` 'JsonValue', required: Discriminator value: JsonValue - `value` union: The JSON value. - object - string[] - string - number, double - boolean - object: A type that represents a list of links to other objects. - `__typename` 'ObjectLinkListValue', required: Discriminator value: ObjectLinkListValue - `value` LinkableDomainObject[]: The list of objects that this value links to. Inaccessible objects may be returned instead if the object is not found with the current permission set. - union: A union representing items that can be linked to. If you have a type that can be linked to, it can only be added once it's in beta. - object: AaSequence variant - … - object: Attachment variant - … - object: Box variant - … - object: Container variant - … - object: CustomEntity variant - … - object: DnaOligo variant - … - object: DnaSequence variant - … - object: DropdownOption variant - … - object: Entry variant - … - object: Inaccessible variant - … - object: Location variant - … - object: MatrixPlate variant - … - object: Mixture variant - … - object: Molecule variant - … - object: OligoConjugate variant - … - object: OligoDuplex variant - … - object: Protein variant - … - object: Result variant - … - object: RnaOligo variant - … - object: RnaSequence variant - … - object: WellPlate variant - … - object: A type that represents links to other objects. - `__typename` 'ObjectLinkValue', required: Discriminator value: ObjectLinkValue - `value` union: A union representing items that can be linked to. If you have a type that can be linked to, it can only be added once it's in beta. - object: AaSequence variant - `__typename` 'AaSequence', required: Discriminator value: AaSequence - `id` string, api_id - object: Attachment variant - `__typename` 'Attachment', required: Discriminator value: Attachment - `id` string, api_id - object: Box variant - `__typename` 'Box', required: Discriminator value: Box - `id` string, api_id - object: Container variant - `__typename` 'Container', required: Discriminator value: Container - `id` string, api_id - object: CustomEntity variant - `__typename` 'CustomEntity', required: Discriminator value: CustomEntity - `id` string, api_id - object: DnaOligo variant - `__typename` 'DnaOligo', required: Discriminator value: DnaOligo - `id` string, api_id - object: DnaSequence variant - `__typename` 'DnaSequence', required: Discriminator value: DnaSequence - `id` string, api_id - object: DropdownOption variant - `__typename` 'DropdownOption', required: Discriminator value: DropdownOption - `id` string, api_id - object: Entry variant - `__typename` 'Entry', required: Discriminator value: Entry - `id` string, api_id - object: Inaccessible variant - `__typename` 'Inaccessible', required: Discriminator value: Inaccessible - `id` string, api_id - object: Location variant - `__typename` 'Location', required: Discriminator value: Location - `id` string, api_id - object: MatrixPlate variant - `__typename` 'MatrixPlate', required: Discriminator value: MatrixPlate - `id` string, api_id - object: Mixture variant - `__typename` 'Mixture', required: Discriminator value: Mixture - `id` string, api_id - object: Molecule variant - `__typename` 'Molecule', required: Discriminator value: Molecule - `id` string, api_id - object: OligoConjugate variant - `__typename` 'OligoConjugate', required: Discriminator value: OligoConjugate - `id` string, api_id - object: OligoDuplex variant - `__typename` 'OligoDuplex', required: Discriminator value: OligoDuplex - `id` string, api_id - object: Protein variant - `__typename` 'Protein', required: Discriminator value: Protein - `id` string, api_id - object: Result variant - `__typename` 'Result', required: Discriminator value: Result - `id` string, api_id - object: RnaOligo variant - `__typename` 'RnaOligo', required: Discriminator value: RnaOligo - `id` string, api_id - object: RnaSequence variant - `__typename` 'RnaSequence', required: Discriminator value: RnaSequence - `id` string, api_id - object: WellPlate variant - `__typename` 'WellPlate', required: Discriminator value: WellPlate - `id` string, api_id - object: A type that represents text (string) values with an associated URL. - `__typename` string, required - `url` string: The URL associated with the value. Please use `TextValue` if you don't want a URL. - `value` string: The text value. It may or may not be an empty string. - object: A type that represents text (string) values. - `__typename` string, required - `value` string: The text value. It may or may not be an empty string. - `studySchema` StudySchemaRef - `__typename` string - `id` string, api_id ## Other responses - `400`: Bad Request - `403`: Forbidden - `404`: Not Found - `409`: Conflict - `429`: Too Many Requests - `500`: Internal Server Error ## Changes - **2026-11-05** `3873a10bf7b8`: 1 breaking, 1 info - added `subschema #1, subschema #8, subschema #9` to the `schemaFields/items/value/oneOf[subschema #1: BenchlingValue]/` response property `oneOf` list for the response status `200` - removed `subschema #1, subschema #8, subschema #9` from the `schemaFields/items/value/oneOf[subschema #1: BenchlingValue]/` response property `oneOf` list for the response status `200` [Operation history](https://skmtc.dev/benchling/apis/benchling-api/changes/api/v3/study/:study_id/patch.md) --- [API](https://skmtc.dev/benchling/apis/benchling-api.md) - [All operations](https://skmtc.dev/benchling/apis/benchling-api/llms.txt) - [OpenAPI document](https://skmtc.dev/benchling/apis/benchling-api/revisions/3873a10bf7b8?raw)