--- title: "Create Entry" method: POST path: "/api/v3/entry" tags: ["Entry"] --- # Create Entry `POST /api/v3/entry` ## Request - Base URL: `https://{tenant_name}.benchling.com` - URL: `https://{tenant_name}.benchling.com/api/v3/entry` - Auth: HTTP bearer Create Entry. ## Headers - `EARLY-ACCESS` string ## Request body - CreateEntryInput - `authorIds` string[]: Specifies user or app IDs to set as entry authors. Defaults to the creator (the authenticated user or app). Use [] to create an entry with no authors. - `folderId` string, required: Specifies the ID of the folder to create the entry in. The folder must grant the caller append permission. The folder ID can be retrieved from the folder listing resource. - `name` string, required: Specifies the entry title. - `parts` DocumentContentInput[]: Specifies the document content parts to create, in order. When provided as an empty array, a blank document is created using the default behavior for its document type. At most 5 attachment parts can be created per request. - union - object: analysis variant - `contentType` 'analysis', required: Discriminator value: analysis - `analysisTemplateId` string, required: Specifies the ID of the analysis template to instantiate and embed. A new analysis is created from the template and the template is applied to it asynchronously after the content is created. The template must be published (draft templates are rejected), and the caller must have permission to apply analysis templates. Analyses can only be embedded in a notebook entry, not other document types. - `indentation` integer: Specifies the indentation level for this content within the document. Accepted values are integers from 0 through 5. - object: attachment variant - `contentType` 'attachment', required: Discriminator value: attachment - `caption` CaptionInput - `formats` TextFormatInput[]: Specifies inline styling applied to character ranges in the plain-text body. - `backgroundColor` string, nullable: Specifies the background color applied to the character range, when set. The value must be a hexadecimal color code such as #RGB or #RRGGBB. - `end` integer, required: Specifies the exclusive end index of the character range within the plain-text body. Accepted values are integers from 1 through the length of the plain-text body. The end index must be greater than the start index. - `foregroundColor` string, nullable: Specifies the text color applied to the character range, when set. The value must be a hexadecimal color code such as #RGB or #RRGGBB. - `properties` TextFormatInputItems[]: Specifies the character style properties applied to the range. - `start` integer, required: Specifies the inclusive start index of the character range within the plain-text body. Accepted values are integers from 0 through the length of the plain-text body. The end index must be greater than the start index. - `links` LinkSpanInput[]: Specifies hyperlinks applied to character ranges in the plain-text body. - `end` integer, required: Specifies the exclusive end index of the character range within the plain-text body. Accepted values are integers from 1 through the length of the plain-text body. The end index must be greater than the start index. - `start` integer, required: Specifies the inclusive start index of the character range within the plain-text body. Accepted values are integers from 0 through the length of the plain-text body. The end index must be greater than the start index. - `url` string, required: Specifies the URL of the hyperlink. Only http and https URLs are accepted. - `mentions` MentionInput[]: Specifies inline mentions of other Benchling items in the plain-text body. - `itemId` string, required: Specifies the ID of the referenced Benchling item. - `position` integer, required: Specifies the zero-based insertion index within the plain-text body where this mention appears. Mentions do not occupy characters in the plain-text body for purposes of format range start and end positions. Accepted values are integers from 0 through the length of the plain-text body. - `text` string, required: Specifies the plain-text body. Character indices in formats, links, and mentions refer to positions in this string. - `displayWidth` integer, nullable: Specifies the custom display width in pixels, when set. The value must be greater than 0. - `indentation` integer: Specifies the indentation level for this content within the document. Accepted values are integers from 0 through 5. - `scratchFileId` string, required: Specifies the ID of a ScratchFile uploaded through the scratch-file workflow. The file upload must be complete before it can be attached. - object: attachment_placeholder variant - `contentType` 'attachment_placeholder', required: Discriminator value: attachment_placeholder - `displayWidth` integer, nullable: Specifies the custom display width in pixels, when set. The value must be greater than 0. - `indentation` integer: Specifies the indentation level for this content within the document. Accepted values are integers from 0 through 5. - object: benchling_item variant - `contentType` 'benchling_item', required: Discriminator value: benchling_item - `indentation` integer: Specifies the indentation level for this content within the document. Accepted values are integers from 0 through 5. - `itemId` string, required: Specifies the ID of the Benchling item to embed. Supported items include sequences, AA sequences, custom entities, oligo conjugates and duplexes, proteins, entries, protocols, and other basic folder items. - object: code_block variant - `contentType` 'code_block', required: Discriminator value: code_block - `text` string, required: Specifies the plain-text body. - object: header variant - `contentType` 'header', required - `formats` TextFormatInput[]: Specifies inline styling applied to character ranges in the plain-text body. - `backgroundColor` string, nullable: Specifies the background color applied to the character range, when set. The value must be a hexadecimal color code such as #RGB or #RRGGBB. - `end` integer, required: Specifies the exclusive end index of the character range within the plain-text body. Accepted values are integers from 1 through the length of the plain-text body. The end index must be greater than the start index. - `foregroundColor` string, nullable: Specifies the text color applied to the character range, when set. The value must be a hexadecimal color code such as #RGB or #RRGGBB. - `properties` TextFormatInputItems[]: Specifies the character style properties applied to the range. - `start` integer, required: Specifies the inclusive start index of the character range within the plain-text body. Accepted values are integers from 0 through the length of the plain-text body. The end index must be greater than the start index. - `headerType` 'HEADER_1' | 'HEADER_2' | 'SUBHEADER_1', required: Specifies the heading level and style. - `indentation` integer: Specifies the indentation level for this content within the document. Accepted values are integers from 0 through 5. - `links` LinkSpanInput[]: Specifies hyperlinks applied to character ranges in the plain-text body. - `end` integer, required: Specifies the exclusive end index of the character range within the plain-text body. Accepted values are integers from 1 through the length of the plain-text body. The end index must be greater than the start index. - `start` integer, required: Specifies the inclusive start index of the character range within the plain-text body. Accepted values are integers from 0 through the length of the plain-text body. The end index must be greater than the start index. - `url` string, required: Specifies the URL of the hyperlink. Only http and https URLs are accepted. - `mentions` MentionInput[]: Specifies inline mentions of other Benchling items in the plain-text body. - `itemId` string, required: Specifies the ID of the referenced Benchling item. - `position` integer, required: Specifies the zero-based insertion index within the plain-text body where this mention appears. Mentions do not occupy characters in the plain-text body for purposes of format range start and end positions. Accepted values are integers from 0 through the length of the plain-text body. - `text` string, required: Specifies the plain-text body. Character indices in formats, links, and mentions refer to positions in this string. - object: list_item variant - `contentType` 'list_item', required - `formats` TextFormatInput[]: Specifies inline styling applied to character ranges in the plain-text body. - `backgroundColor` string, nullable: Specifies the background color applied to the character range, when set. The value must be a hexadecimal color code such as #RGB or #RRGGBB. - `end` integer, required: Specifies the exclusive end index of the character range within the plain-text body. Accepted values are integers from 1 through the length of the plain-text body. The end index must be greater than the start index. - `foregroundColor` string, nullable: Specifies the text color applied to the character range, when set. The value must be a hexadecimal color code such as #RGB or #RRGGBB. - `properties` TextFormatInputItems[]: Specifies the character style properties applied to the range. - `start` integer, required: Specifies the inclusive start index of the character range within the plain-text body. Accepted values are integers from 0 through the length of the plain-text body. The end index must be greater than the start index. - `indentation` integer: Specifies the indentation level for this content within the document. Accepted values are integers from 1 through 5. - `links` LinkSpanInput[]: Specifies hyperlinks applied to character ranges in the plain-text body. - `end` integer, required: Specifies the exclusive end index of the character range within the plain-text body. Accepted values are integers from 1 through the length of the plain-text body. The end index must be greater than the start index. - `start` integer, required: Specifies the inclusive start index of the character range within the plain-text body. Accepted values are integers from 0 through the length of the plain-text body. The end index must be greater than the start index. - `url` string, required: Specifies the URL of the hyperlink. Only http and https URLs are accepted. - `listType` 'BULLET' | 'NUMBER' | 'CHECKBOX_CHECKED' | 'CHECKBOX_UNCHECKED', required: Specifies the list marker style. - `mentions` MentionInput[]: Specifies inline mentions of other Benchling items in the plain-text body. - `itemId` string, required: Specifies the ID of the referenced Benchling item. - `position` integer, required: Specifies the zero-based insertion index within the plain-text body where this mention appears. Mentions do not occupy characters in the plain-text body for purposes of format range start and end positions. Accepted values are integers from 0 through the length of the plain-text body. - `text` string, required: Specifies the plain-text body. Character indices in formats, links, and mentions refer to positions in this string. - object: results_table variant - `contentType` 'results_table', required - `indentation` integer - `name` string, required: Specifies the display name of the table. The name must not be empty or blank, and must be at most 100 characters. - `resultSchemaId` string, required: Specifies the ID of the result schema that defines the table's columns. The schema ID can be retrieved from the result schema listing resource. - object: section variant - `contentType` 'section', required - `date` union: Specifies the section date, when set. Sections with dates must be in chronological order. - string - string, date - `title` string: Specifies the section title, when set. - object: text variant - `contentType` 'text', required - `formats` TextFormatInput[]: Specifies inline styling applied to character ranges in the plain-text body. - `backgroundColor` string, nullable: Specifies the background color applied to the character range, when set. The value must be a hexadecimal color code such as #RGB or #RRGGBB. - `end` integer, required: Specifies the exclusive end index of the character range within the plain-text body. Accepted values are integers from 1 through the length of the plain-text body. The end index must be greater than the start index. - `foregroundColor` string, nullable: Specifies the text color applied to the character range, when set. The value must be a hexadecimal color code such as #RGB or #RRGGBB. - `properties` TextFormatInputItems[]: Specifies the character style properties applied to the range. - `start` integer, required: Specifies the inclusive start index of the character range within the plain-text body. Accepted values are integers from 0 through the length of the plain-text body. The end index must be greater than the start index. - `indentation` integer: Specifies the indentation level for this content within the document. Accepted values are integers from 0 through 5. - `links` LinkSpanInput[]: Specifies hyperlinks applied to character ranges in the plain-text body. - `end` integer, required: Specifies the exclusive end index of the character range within the plain-text body. Accepted values are integers from 1 through the length of the plain-text body. The end index must be greater than the start index. - `start` integer, required: Specifies the inclusive start index of the character range within the plain-text body. Accepted values are integers from 0 through the length of the plain-text body. The end index must be greater than the start index. - `url` string, required: Specifies the URL of the hyperlink. Only http and https URLs are accepted. - `mentions` MentionInput[]: Specifies inline mentions of other Benchling items in the plain-text body. - `itemId` string, required: Specifies the ID of the referenced Benchling item. - `position` integer, required: Specifies the zero-based insertion index within the plain-text body where this mention appears. Mentions do not occupy characters in the plain-text body for purposes of format range start and end positions. Accepted values are integers from 0 through the length of the plain-text body. - `text` string, required: Specifies the plain-text body. Character indices in formats, links, and mentions refer to positions in this string. - object: unstructured_table variant - `contentType` 'unstructured_table', required - `caption` CaptionInput - `formats` TextFormatInput[]: Specifies inline styling applied to character ranges in the plain-text body. - `backgroundColor` string, nullable: Specifies the background color applied to the character range, when set. The value must be a hexadecimal color code such as #RGB or #RRGGBB. - `end` integer, required: Specifies the exclusive end index of the character range within the plain-text body. Accepted values are integers from 1 through the length of the plain-text body. The end index must be greater than the start index. - `foregroundColor` string, nullable: Specifies the text color applied to the character range, when set. The value must be a hexadecimal color code such as #RGB or #RRGGBB. - `properties` TextFormatInputItems[]: Specifies the character style properties applied to the range. - `start` integer, required: Specifies the inclusive start index of the character range within the plain-text body. Accepted values are integers from 0 through the length of the plain-text body. The end index must be greater than the start index. - `links` LinkSpanInput[]: Specifies hyperlinks applied to character ranges in the plain-text body. - `end` integer, required: Specifies the exclusive end index of the character range within the plain-text body. Accepted values are integers from 1 through the length of the plain-text body. The end index must be greater than the start index. - `start` integer, required: Specifies the inclusive start index of the character range within the plain-text body. Accepted values are integers from 0 through the length of the plain-text body. The end index must be greater than the start index. - `url` string, required: Specifies the URL of the hyperlink. Only http and https URLs are accepted. - `mentions` MentionInput[]: Specifies inline mentions of other Benchling items in the plain-text body. - `itemId` string, required: Specifies the ID of the referenced Benchling item. - `position` integer, required: Specifies the zero-based insertion index within the plain-text body where this mention appears. Mentions do not occupy characters in the plain-text body for purposes of format range start and end positions. Accepted values are integers from 0 through the length of the plain-text body. - `text` string, required: Specifies the plain-text body. Character indices in formats, links, and mentions refer to positions in this string. - `columnDefinitions` UnstructuredTableColumnInput[], required: Specifies the column definitions for the table. The table must have at least one column, but no more than 255. - `isLocked` boolean - `name` string, required: Specifies the column display name. - `width` integer, nullable - `name` string, required: Specifies the display name of the table. The name must not be empty. - `rows` UnstructuredTableRowInput[], required: Specifies the rows in the table. The table must have at least one row. Each row must contain one cell for each column. - `cells` UnstructuredTableCellInput[], required: Specifies the cells in the row, in column order. - `format` TableCellFormatInput - … - `inputValue` TextValueInput, required - … - `mergeRange` TableMergeRangeInput - … - `selectorId` string, nullable: Specifies the ID of a table cell selector to associate with this cell. - `schemaFields` object: Specifies values for fields defined by the entry schema. Keys must be field API identifiers. Values must be API identifiers or JSON values matching the field type. Exceptions are assay run and assay result link fields, which must be warehouse UUIDs. Permitted only when the entry has a schema associated with it, or schemaId is supplied in the same request. - `schemaId` string: Specifies the ID of the entry schema to assign. Omit to create an entry without an entry schema. The schema ID can be retrieved from the entry schema listing resource. - `studyAssociations` StudyAssociationInput[]: Specifies study associations, including auto-linking behavior. This is used to associate the entry with studies. - `isAutoLinking` boolean: Specifies whether items created within this item are automatically associated with the study. Defaults to false. - `studyId` string, required: Specifies the ID of the study to associate with the item. The study ID can be retrieved from the study listing resource. - `studyIds` string[]: Deprecated: use `studyAssociations` instead, which also supports auto-linking. Specifies study IDs to associate with the new entry. Study IDs can be retrieved from the study listing resource. ## Response `201` Created - Entry: Represents a notebook entry in Benchling's electronic lab notebook. Scientists use entries to record experimental work, observations, and supporting data such as text, tables, file attachments, and results tables. Entries support authorship, custom fields, folder organization, optional entry schemas, review workflows, and project-based access control. Document content is available as ordered document parts. - `__typename` string - `applicableReviewProcesses` string, uri: Lists review processes configured for the entry's project. Use the paginated list of applicable review processes for the full list including stages and version details. - `archiveReason` string, nullable: Specifies the archive reason when the entry is archived. - `archived` boolean: Specifies whether the entry is archived. - `createdAt` string, datetime, nullable: Specifies when the entry was created. - `customFields` CustomField[], nullable: Lists custom field values on the entry. - `__typename` string - `name` string, nullable - `value` string, nullable - `displayId` string, nullable: Specifies the display ID for the entry. - `folder` FolderRef - `__typename` string - `id` string, api_id - `id` string: Identifies the entry. - `modifiedAt` string, datetime, nullable: Specifies when the entry was last modified. - `name` string, nullable: Specifies the title of the entry. - `review` ReviewRef - `__typename` string - `id` string, api_id - `reviewSource` ProjectRef - `__typename` string - `id` string, api_id - `schema` EntrySchemaRef - `__typename` string - `id` string, api_id - `selectors` TableCellSelector[]: Lists dropdown selectors available to table cells in the document. - `__typename` string - `name` string: Specifies the display name of the selector. - `options` string[]: Lists the allowed dropdown option values. - `selectorId` string: Specifies the selector identifier within the document. Matches the selectorId field on table cells. - `typedSchema` EntrySchemaRef - `__typename` string - `id` string, api_id - `versionMetadata` DocumentLikeVersionMetadata: Version metadata for a document such as an entry, template, or subtemplate. Identifies a specific content revision and records when that revision was produced. Use this to detect changes, pin a revision, or reference a particular version without loading the full version record. - `__typename` string - `createdAt` string, datetime, nullable: Specifies when this version was created. Versions are immutable; this is the time the parent document was last edited to produce this revision. - `versionId` string: Identifies this version of the document. - `webUrl` string: Specifies the absolute URL of the entry in the Benchling web app. - `authors` string, uri, nullable: Lists the authors of the entry. Defaults to the creator but may be edited. - `creator` PrincipalRef - `__typename` string - `id` string, api_id - `parts` string, uri: Lists ordered document parts that make up the document content. - `schemaFields` SchemaFieldValue[], nullable: Lists values for fields defined by the entry schema. - `__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: Run 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: Run variant - `__typename` 'Run', required: Discriminator value: Run - `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. ## 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)