Update Study | Benchling Documentation

curl -X PATCH https://{tenant_name}.benchling.com/api/v3/study/study_id \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "archiveReason": "Archived",
  "archived": true,
  "authorIds": [
    "ent_a0SApq3z",
    "ent_t40Vb4aA"
  ],
  "description": "Updated Study Description",
  "designEntry": {
    "folderId": "lib_o2thOLlq",
    "name": "New Design Entry"
  },
  "displayId": "CSWNAR1",
  "folderId": "lib_o2thOLlq",
  "name": "Updated Study Name",
  "phase": "EXECUTION",
  "schemaFields": {
    "boolean_field_system_name": {
      "value": false
    },
    "date_field_system_name": {
      "value": "2025-06-15"
    },
    "datetime_field_system_name": {
      "value": "2025-06-15T09:00:00Z"
    },
    "dropdown_field_system_name": {
      "value": "sfso_UcQuhAwx"
    },
    "entity_field_system_name": {
      "value": [
        "bfi_jdf8BV24"
      ]
    },
    "number_field_system_name": {
      "value": 456
    },
    "text_field_system_name": {
      "value": "Updated text value"
    }
  }
}'

{
  "__typename": "__typename",
  "archiveReason": "archiveReason",
  "archived": true,
  "authors": "authors",
  "createdAt": "createdAt",
  "creator": {
    "__typename": "__typename",
    "id": "id"
  },
  "description": "description",
  "designEntry": {
    "__typename": "__typename",
    "id": "id"
  },
  "displayId": "displayId",
  "folder": {
    "__typename": "__typename",
    "id": "id"
  },
  "id": "id",
  "modifiedAt": "modifiedAt",
  "name": "name",
  "phase": "DESIGN",
  "schema": {
    "__typename": "__typename",
    "id": "id"
  },
  "schemaFields": [
    {
      "__typename": "__typename",
      "id": "id",
      "linkedEntityId": "linkedEntityId"
    }
  ],
  "studySchema": {
    "__typename": "__typename",
    "id": "id"
  },
  "archiveUser": {
    "__typename": "__typename",
    "id": "id"
  }
}

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.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

study_idstringRequired

ID of the Study.

Request

This endpoint expects an object.

archiveReasonstringOptional

archivedbooleanOptional

authorIdslist of stringsOptional

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.

descriptionstringOptional

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

designEntryobjectOptional

Create a new entry to use as the study design entry. Cannot be combined with designEntryId.

designEntryIdstring or nullOptional

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.

displayIdstringOptional

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.

folderIdstringOptional

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

namestringOptional

The name of the study. Omit to leave unchanged.

phaseenumOptional

The lifecycle phase of the study. Omit to leave unchanged. See the endpoint description for transition rules.

Allowed values:

schemaFieldsmap from strings to objectsOptional

fieldValueslist of objectsOptionalDeprecated

Use schemaFields instead.

Response

__typenamestringOptional

archiveReasonstring or nullOptional

archivedbooleanOptional

authorsstring or nullOptionalformat: "uri"

Users and apps designated as authors of the study.

createdAtstring or nullOptional

creatorobjectOptional

descriptionstring or nullOptional

designEntryobject or nullOptional

displayIdstring or nullOptional

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.

folderobjectOptional

idstringOptional

modifiedAtstring or nullOptional

namestringOptional

phaseenum or nullOptional

Allowed values:

schemaobject or nullOptional

schemaFieldslist of objects or nullOptional

studySchemaobjectOptional

Use schema instead. The schema of the study.

archiveDatetimestring or nullOptionalDeprecated

No longer supported.

archiveUserobject or nullOptionalDeprecated

No longer supported.

Errors

400

Study Update Request Bad Request Error

403

Study Update Request Forbidden Error

404

Study Update Request Not Found Error

409

Study Update Request Conflict Error

429

Study Update Request Too Many Requests Error

500

Study Update Request Internal Server Error