BEbenchling
Study

Update Study

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.
patch/api/v3/study/{study_id}

Request

  • Base URL
    https://{tenant_name}.benchling.com
  • Auth
    HTTP bearer

Path parameters

study_idstring required

ID of the Study.

Request body

archiveReasonstring

Why it is being archived. Required when archived is true, and not allowed when unarchiving.

archivedboolean

Set to true to archive or false to unarchive it. Archiving requires archiveReason.

authorIdsstring[]

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.

descriptionstring

The description of the study. Omit to leave unchanged. Max 2048 characters.

designEntryIdstring 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.

displayIdstring

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.

folderIdstring

The ID of the folder to move the study to. Omit to leave unchanged.

namestring

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.

schemaFieldsobject

Response

OK

__typenamestring
archiveDatetimestring datetime nullable

No longer supported.

archiveReasonstring nullable
archivedboolean
authorsstring uri nullable

Users and apps designated as authors of the study.

createdAtstring datetime nullable
descriptionstring nullable
displayIdstring 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.

idstring
modifiedAtstring datetime nullable
namestring
phase'DESIGN' | 'EXECUTION' | 'COMPLETE'

Changes

No recorded changes to this operation across all 1 revision of this API.