--- title: "Create StudySchema" method: POST path: "/api/v3/study-schema" tags: ["Study Schema"] --- # Create StudySchema `POST /api/v3/study-schema` ## Request - Base URL: `https://{tenant_name}.benchling.com` - URL: `https://{tenant_name}.benchling.com/api/v3/study-schema` - Auth: HTTP bearer Create a study schema. ## ID generation - For `AUTO_GENERATED_FROM_PREFIX`, provide a non-empty, unique `prefix`. New studies receive IDs generated from that prefix. - For `MANUAL`, omit `prefix` or provide an empty value. Callers must provide IDs when creating studies with this schema. ## Study-type restrictions - `entryTemplateIds` associates entry templates with the schema and is supported only for `CUSTOM` study schemas. Provide at most 50 IDs. - `isDesignApprovalRequired` is supported for `CUSTOM` schemas and, when design review is enabled for the tenant, for `CLINICAL` and `PRECLINICAL` schemas. It is not supported for `PROCESS_DEVELOPMENT` or `ASSAY_DEVELOPMENT` schemas. ## Request body - CreateStudySchemaInput - `description` string, required: A human-readable description of the schema. At most 1000 characters. - `displayName` string: Deprecated. Use name instead. - `entryTemplateIds` string[]: Entry template IDs associated with this schema. - `fieldDefinitions` CreateStudySchemaInputFieldDefinitionsItems[]: Field definitions for this schema. - union - CreateBooleanFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isRequired` boolean, required: When true, a value must be provided for this field. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'BOOLEAN', required - CreateDateFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isRequired` boolean, required: When true, a value must be provided for this field. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'DATE', required - CreateDateTimeFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isRequired` boolean, required: When true, a value must be provided for this field. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'DATE_TIME', required - CreateDecimalFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `displayPrecision` integer: The number of decimal places to display (0 to 10). - `isRequired` boolean, required: When true, a value must be provided for this field. - `legalTextDropdownId` string: The API ID of the legal text dropdown associated with this field definition. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `numericMax` number, double: The maximum allowed value, inclusive. - `numericMin` number, double: The minimum allowed value, inclusive. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'DECIMAL', required - `unitId` string: The API ID of the unit to associate with this field. - CreateIntegerFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isRequired` boolean, required: When true, a value must be provided for this field. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `numericMax` number, double: The maximum allowed value, inclusive. - `numericMin` number, double: The minimum allowed value, inclusive. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'INTEGER', required - `unitId` string: The API ID of the unit to associate with this field. - CreateJsonFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isRequired` boolean, required: When true, a value must be provided for this field. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'JSON', required - CreateLongTextFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isRequired` boolean, required: When true, a value must be provided for this field. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'LONG_TEXT', required - CreateTextFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isRequired` boolean, required: When true, a value must be provided for this field. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'TEXT', required - CreateAaSequenceLinkFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isMulti` boolean, required: When true, multiple linked values are allowed. - `isParent` boolean: When true, indicates a parent-child relationship used in the registry's lot-numbering functionality. - `isRequired` boolean, required: When true, a value must be provided for this field. - `linkDefinitionId` string, nullable, required: The API ID of the schema to constrain links to, or null to allow links to any item of the linked type. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'AA_SEQUENCE_LINK', required - CreateProteinLinkFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isMulti` boolean, required: When true, multiple linked values are allowed. - `isParent` boolean: When true, indicates a parent-child relationship used in the registry's lot-numbering functionality. - `isRequired` boolean, required: When true, a value must be provided for this field. - `linkDefinitionId` string, nullable, required: The API ID of the schema to constrain links to, or null to allow links to any item of the linked type. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'PROTEIN_LINK', required - CreateAnyEntityLinkFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isMulti` boolean, required: When true, multiple linked values are allowed. - `isRequired` boolean, required: When true, a value must be provided for this field. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'ENTITY_LINK', required - CreateAttachmentLinkFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isMulti` boolean, required: When true, multiple linked values are allowed. - `isRequired` boolean, required: When true, a value must be provided for this field. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'ATTACHMENT_LINK', required - CreateCustomEntityLinkFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isMulti` boolean, required: When true, multiple linked values are allowed. - `isParent` boolean: When true, indicates a parent-child relationship used in the registry's lot-numbering functionality. - `isRequired` boolean, required: When true, a value must be provided for this field. - `linkDefinitionId` string, nullable, required: The API ID of the schema to constrain links to, or null to allow links to any item of the linked type. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'CUSTOM_ENTITY_LINK', required - CreateDnaSequenceLinkFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isMulti` boolean, required: When true, multiple linked values are allowed. - `isParent` boolean: When true, indicates a parent-child relationship used in the registry's lot-numbering functionality. - `isRequired` boolean, required: When true, a value must be provided for this field. - `linkDefinitionId` string, nullable, required: The API ID of the schema to constrain links to, or null to allow links to any item of the linked type. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'DNA_SEQUENCE_LINK', required - CreateDropdownLinkFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `dropdownId` string, required: The API ID of the Dropdown that defines the available options. - `isMulti` boolean, required: When true, multiple linked values are allowed. - `isRequired` boolean, required: When true, a value must be provided for this field. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'DROPDOWN', required - CreateEquipmentLinkFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isMulti` boolean, required: When true, multiple linked values are allowed. - `isParent` boolean: When true, indicates a parent-child relationship used in the registry's lot-numbering functionality. - `isRequired` boolean, required: When true, a value must be provided for this field. - `linkDefinitionId` string, nullable, required: The API ID of the schema to constrain links to, or null to allow links to any item of the linked type. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'EQUIPMENT_LINK', required - CreateFieldsetLinkFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isMulti` boolean, required: When true, multiple linked values are allowed. - `isParent` boolean: When true, indicates a parent-child relationship used in the registry's lot-numbering functionality. - `isRequired` boolean, required: When true, a value must be provided for this field. - `linkDefinitionId` string, required: The API ID of the schema/interface that linked items must belong to. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'FIELDSET_LINK', required - CreateMixtureLinkFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isMulti` boolean, required: When true, multiple linked values are allowed. - `isParent` boolean: When true, indicates a parent-child relationship used in the registry's lot-numbering functionality. - `isRequired` boolean, required: When true, a value must be provided for this field. - `linkDefinitionId` string, nullable, required: The API ID of the schema to constrain links to, or null to allow links to any item of the linked type. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'MIXTURE_LINK', required - CreateMoleculeLinkFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isMulti` boolean, required: When true, multiple linked values are allowed. - `isParent` boolean: When true, indicates a parent-child relationship used in the registry's lot-numbering functionality. - `isRequired` boolean, required: When true, a value must be provided for this field. - `linkDefinitionId` string, nullable, required: The API ID of the schema to constrain links to, or null to allow links to any item of the linked type. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'MOLECULE_LINK', required - CreateOligoConjugateLinkFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isMulti` boolean, required: When true, multiple linked values are allowed. - `isParent` boolean: When true, indicates a parent-child relationship used in the registry's lot-numbering functionality. - `isRequired` boolean, required: When true, a value must be provided for this field. - `linkDefinitionId` string, nullable, required: The API ID of the schema to constrain links to, or null to allow links to any item of the linked type. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'OLIGO_CONJUGATE_LINK', required - CreateOligoDuplexLinkFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isMulti` boolean, required: When true, multiple linked values are allowed. - `isParent` boolean: When true, indicates a parent-child relationship used in the registry's lot-numbering functionality. - `isRequired` boolean, required: When true, a value must be provided for this field. - `linkDefinitionId` string, nullable, required: The API ID of the schema to constrain links to, or null to allow links to any item of the linked type. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'OLIGO_DUPLEX_LINK', required - CreateRnaSequenceLinkFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isMulti` boolean, required: When true, multiple linked values are allowed. - `isParent` boolean: When true, indicates a parent-child relationship used in the registry's lot-numbering functionality. - `isRequired` boolean, required: When true, a value must be provided for this field. - `linkDefinitionId` string, required: The API ID of the schema/interface that linked items must belong to. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'RNA_SEQUENCE_LINK', required - CreateStorableLinkFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isMulti` boolean, required: When true, multiple linked values are allowed. - `isRequired` boolean, required: When true, a value must be provided for this field. - `linkDefinitionId` string, nullable, required: The API ID of the schema to constrain links to, or null to allow links to any item of the linked type. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'STORAGE_LINK', required - CreateSystemCategoryLinkFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isMulti` boolean, required: When true, multiple linked values are allowed. - `isRequired` boolean, required: When true, a value must be provided for this field. - `linkDefinitionId` string, required: The API ID of the schema/interface that linked items must belong to. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'SYSTEM_CATEGORY_LINK', required - `idGenerationMode` 'AUTO_GENERATED_FROM_PREFIX' | 'MANUAL', required: How study IDs are assigned for studies created from this schema. AUTO_GENERATED_FROM_PREFIX requires a non-empty prefix and does not accept a caller-provided ID. MANUAL requires an empty prefix. A study ID may be provided at creation, and if omitted the server generates one. - `isDesignApprovalRequired` boolean: Whether design approval is required for studies of this schema. - `name` string: The user-facing name of the schema. Must be non-empty after stripping whitespace, at most 255 characters, and unique within the organization. - `organizationId` string, required: The API ID of the organization this schema belongs to. The organization must exist and be accessible to the caller. - `prefix` string: ID prefix for studies of this schema. - `studyType` 'CUSTOM' | 'PROCESS_DEVELOPMENT' | 'ASSAY_DEVELOPMENT' | 'CLINICAL' | 'PRECLINICAL', required: Type of studies created from this schema. - `systemName` string: The SQL identifier used as the warehouse table name. If not provided, one is auto-generated from the display name. Must match the pattern [a-z_][a-z0-9_$]*, cannot be a reserved table name, cannot start with 'bnch$', and must be unique within the organization. ## Response `201` Created - StudySchema: A configuration template that defines the structure and behavior of Studies within an organization. Each `StudySchema` specifies the `studyType`, which determines available features and workflow capabilities. Schemas define custom fields through `fieldDefinitions` that studies of this type must populate. The `isDesignApprovalRequired` flag controls whether study designs must go through a review process before execution. Associated `entryTemplates` provide standardized notebook templates for documenting study work. Studies reference their schema via `Study.studySchema`. - `__typename` string - `archiveReason` string, nullable - `archived` boolean - `createdAt` string, datetime, nullable - `creator` PrincipalRef - `__typename` string - `id` string, api_id - `description` string: A description of this study schema for documentation purposes. - `entryTemplates` string, uri - `fieldDefinitions` string, uri - `id` string - `idGenerationMode` 'AUTO_GENERATED_FROM_PREFIX' | 'MANUAL': How Study IDs are assigned for studies of this schema. - `isDesignApprovalRequired` boolean - `modifiedAt` string, datetime, nullable - `name` string - `organization` OrganizationRef - `__typename` string - `id` string, api_id - `prefix` string, nullable - `studyType` 'CUSTOM' | 'PROCESS_DEVELOPMENT' | 'ASSAY_DEVELOPMENT' | 'CLINICAL' | 'PRECLINICAL' ## Other responses - `400`: Bad Request - `403`: Forbidden - `404`: Not Found - `409`: Conflict - `429`: Too Many Requests - `500`: Internal Server Error --- [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/c9f087b98b8b?raw)