--- title: "Create Study" method: POST path: "/api/v3/study" tags: ["Study"] --- # Create Study `POST /api/v3/study` ## Request - Base URL: `https://{tenant_name}.benchling.com` - URL: `https://{tenant_name}.benchling.com/api/v3/study` - Auth: HTTP bearer Create a study in a folder. ## Always required | Field | Description | | --- | --- | | `description` | Description of the study. May be an empty string, up to 2048 characters. | | `folderId` | Target folder ID. List folders with the folder list endpoint. | | A schema pair | One schema-fields pair, see below. | ## Schema fields Provide exactly one of these pairs. Do not mix them: - `schemaId` with `schemaFields` (preferred). Keys in `schemaFields` must be field **system names** or field API IDs, not display names. - The deprecated `studySchemaId` with the deprecated `tags`. Keys in `tags` must be field display names or field API IDs. List schemas with the study-schema list endpoint. See the request example for supported field value shapes. ## name - **Required** when the study schema has no naming template. - **Must be omitted** when the schema has a naming template (the server generates the name). ## designEntryId - **Required** when the schema's `studyType` is `CUSTOM`. - **Must be omitted** for every other `studyType`. - Read `studyType` from the study-schema get-by-ID endpoint. List entries with the entry list endpoint. A design entry can belong to only one study. ## displayId Behavior depends on the schema's `idGenerationMode`, which you can read from the study-schema get-by-ID endpoint: - `AUTO_GENERATED_FROM_PREFIX`: **omit** `displayId`. The server assigns an ID from the schema prefix. Providing `displayId` fails validation. - `MANUAL`: you **may** provide `displayId` (must be unique within the tenant), or omit it to have the server generate one. ## authorIds - Omit to default authors to the creator. - Provide an array of user or app IDs to set a specific author list. List users with the user list endpoint. - Pass an empty array to create the study without authors. - Do not pass `null`. > The request example includes `name`, `designEntryId`, and `displayId` together for a Custom study on a MANUAL schema with no naming template. Other schema configurations require a different subset of these fields. ## Request body - CreateStudyInput - `authorIds` string[]: The IDs of the users or apps to set as study authors. Omit to default to the creator. Pass an empty array to create the study without authors. - `description` string, required - `designEntryId` string: The ID of an entry to use as the study design entry. Optional for custom studies. Should always be omitted for all other study types. - `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. - `folderId` string, required: The ID of the folder to create the study in. - `name` string: The name of the study. Should be omitted if using a study schema with a naming template. - `schemaFields` object - `schemaId` string: The ID of the schema to associate with this object. - `studySchemaId` string: Deprecated. Use `schemaId` instead. The ID of the study schema. - `tags` CreateStudyInputTags: Deprecated. Use `schemaFields` instead. Schema fields to set on the study. Must correspond with the study schema's field definitions. Every field should have its display name (not system name) or API ID as a key, mapping to the value of the field. See the example for the supported field value types and formatting. For date and datetime fields, use the RFC 3339 format. For single link fields, supply a single object specifying the id of the item you want to link, (eg. `{'targetFiles': [{'id': 'bfi_jdf8BV24'}]}`). For multi-link fields, supply an array of objects specifying the ids of the items you want to link, (eg. `{'targetFiles': [{'id': 'bfi_jdf8BV24'}, {'id': 'bfi_laGnl8vB'}]}`). Must be paired with the deprecated `studySchemaId`, not `schemaId`. Prefer `schemaId` with `schemaFields` instead. ## Response `201` Created - 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 `201` - removed `subschema #1, subschema #8, subschema #9` from the `schemaFields/items/value/oneOf[subschema #1: BenchlingValue]/` response property `oneOf` list for the response status `201` [Operation history](https://skmtc.dev/benchling/apis/benchling-api/changes/api/v3/study/post.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)