--- title: "Batch create Study" method: POST path: "/api/v3/study:batch-create" tags: ["Study"] --- # Batch create Study `POST /api/v3/study:batch-create` ## Request - Base URL: `https://{tenant_name}.benchling.com` - URL: `https://{tenant_name}.benchling.com/api/v3/study:batch-create` - Auth: HTTP bearer Batch create Study synchronously in one transaction. Maximum 25 items per request. ## Request body - object - `items` CreateStudyInput[], required - `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 - StudyBatchcreateResponse201 - `items` Study[], required - `__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. - `__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: 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 - … - 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 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 `items/items/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 `items/items/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:batch-create/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)