> This page is for Developer Documentation. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.benchling.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.benchling.com/_mcp/server. # Create a notebook entry POST https://{tenant_name}.benchling.com/api/v2/entries Content-Type: application/json Create a notebook entry Reference: https://docs.benchling.com/docs/api/v2/benchling-api/entries/create-entry ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Body (application/json) This endpoint expects an EntryCreate. - `folderId` (string, required) — ID of the folder that will contain the entry - `name` (string, required) — Name of the entry - `authorIds` (EntryCreateAuthorIds, optional) - `customFields` (map from string to CustomField, optional) — Custom fields to add to the entry - `entryTemplateId` (string, optional) — ID of the template to clone the entry from - `fields` (map from string to Field, optional) — Fields to set on the entry. Must correspond with the schema's field definitions. - `initialTables` (list of InitialTable, optional) — An array of table API IDs and blob id pairs to seed tables from the template while creating the entry. The entryTemplateId parameter must be set to use this parameter. The table API IDs should be the API Identifiers of the tables in the given template. - If a template table has one row, the values in that row act as default values for cloned entries. - If a template table has multiple rows, there is no default value and those rows are added to the cloned entry along with the provided csv data. - If a table has default values, they will be populated in any respective undefined columns in the csv data. - If a table has no default values, undefined columns from csv data will be empty. - If no csv data is provided for a table, the table in the entry will be populated with whatever values are in the respective template table. - `schemaId` (string, optional) — ID of the entry's schema ## Response ### 201 Created - `apiURL` (string, optional) — The canonical url of the Entry in the API. - `archiveRecord` (ArchiveRecord, optional, nullable) — ArchiveRecord Resource if the entry is archived. This is null if the entry is not archived. - `assignedReviewers` (list of UserSummary, optional) — Array of users assigned to review the entry, if any. - `authors` (list of UserSummary, optional) — Array of UserSummary Resources of the authors of the entry. This defaults to the creator but can be manually changed. - `createdAt` (datetime, optional) — DateTime the entry was created at - `creator` (UserSummary, optional) — UserSummary Resource of the user who created the entry - `customFields` (map from string to CustomField, optional) - `days` (list of EntryDay, optional) — Array of day objects. Each day object has a date field (string) and notes field (array of notes, expand further for details on note types). - `displayId` (string, optional) — User-friendly ID of the entry - `entryTemplateId` (string, optional, nullable) — ID of the Entry Template this Entry was created from - `fields` (map from string to Field, optional) - `folderId` (string, optional) — ID of the folder that contains the entry - `id` (string, optional) — ID of the entry - `modifiedAt` (string, optional) — DateTime the entry was last modified - `name` (string, optional) — Title of the entry - `reviewRecord` (EntryReviewRecord, optional, nullable) — Review record if set - `schema` (EntrySchema, optional, nullable) — Entry schema if set - `webURL` (string, optional) — URL of the entry ## Errors ### 400 Bad Request Error Bad Request - `error` (BadRequestErrorError, optional) ## Types ### EntryCreateAuthorIds ### CustomField - `value` (string, optional) ### Field - `value` (FieldValue, required, nullable) — For single link fields, use the id of the item you want to link (eg. "seq_jdf8BV24"). For multi-link fields, use an array of ids of the items you want to link (eg. ["seq_jdf8BV24"]) - `displayValue` (string, optional, nullable) - `isMulti` (boolean, optional) - `textValue` (string, optional, nullable) - `type` (enum, optional) - Allowed values: `dna_sequence_link`, `aa_sequence_link`, `custom_entity_link`, `entity_link`, `mixture_link`, `molecule_link`, `dropdown`, `part_link`, `translation_link`, `aa_part_link`, `base_molecule_link`, `blob_link`, `text`, `long_text`, `batch_link`, `storage_link`, `entry_link`, `assay_request_link`, `assay_result_link`, `assay_run_link`, `boolean`, `float`, `integer`, `datetime`, `date`, `json` ### InitialTable - `csvData` (string, optional) — blobId of an uploaded csv blob. The CSV should be formatted with column headers of `columnId` which can be found in the [EntryTemplate](#/components/schemas/EntryTemplate). For more information on uploading a blob, [click here](https://docs.benchling.com/docs/uploading-a-blob-to-benchling). - `templateTableID` (string, optional) — Template table API ID ### ArchiveRecord - `reason` (string, optional) ### UserSummary - `handle` (string, optional) - `id` (string, optional) - `name` (string, optional) ### EntryDay - `date` (string, optional) — A Date string - `notes` (list of EntryNotePart, optional) - `title` (string, optional, nullable) — Optional title of a section if sections are enabled. ### EntryReviewRecord Review record if set - `comment` (string, optional) — Reviewer's Comments - `reviewChanges` (list of ReviewChange, optional) — A list of the Review Changes that have been made to this entry - `reviewProcesses` (list of EntryReviewProcess, optional, nullable) — Review Processes associated with the Entry - `status` (enum, optional) — Review Status of the entry - Allowed values: `ACCEPTED`, `NEEDS_REVIEW`, `REJECTED`, `RETRACTED`, `ACCEPTANCE_SNAPSHOT_IN_PROGRESS`, `REVIEW_SNAPSHOT_IN_PROGRESS`, `IN_PROGRESS`, `ACTION_REQUIRED` ### EntrySchema Entry schema - `id` (string, optional) — ID of the entry schema - `modifiedAt` (datetime, optional) — DateTime the Entry Schema was last modified - `name` (string, optional) — Name of the entry schema ### BadRequestErrorError - `message` (string, optional) - `type` (enum, optional) - Allowed values: `invalid_request_error` - `userMessage` (string, optional) ### FieldValue For single link fields, use the id of the item you want to link (eg. "seq_jdf8BV24"). For multi-link fields, use an array of ids of the items you want to link (eg. ["seq_jdf8BV24"]) ### EntryNotePart Notes are the main building blocks of entries. Each note corresponds roughly to a paragraph. - `type`: `app_canvas` (app_canvas) - `appId` (string, optional) — The API identifier for the Benchling App. - `canvasId` (string, optional) — The API identifier for this Analysis Chart. - `featureId` (string, optional) — The developer ID assigned to the feature of this App Canvas. - `indentation` (integer, optional, default: 0) — All notes have an indentation level - the default is 0 for no indent. For lists, indentation gives notes hierarchy - a bulleted list with children is modeled as one note part with indentation 1 followed by note parts with indentation 2, for example. - `type`: `assay_run` (assay_run) - `assayRunId` (string, optional, nullable) - `assayRunSchemaId` (string, optional) - `indentation` (integer, optional, default: 0) — All notes have an indentation level - the default is 0 for no indent. For lists, indentation gives notes hierarchy - a bulleted list with children is modeled as one note part with indentation 1 followed by note parts with indentation 2, for example. - `type`: `box_creation_table` (box_creation_table) - `apiId` (string, optional) - `boxSchemaId` (string, optional) - `columns` (list of StructuredTableColumnInfo, optional) - `indentation` (integer, optional, default: 0) — All notes have an indentation level - the default is 0 for no indent. For lists, indentation gives notes hierarchy - a bulleted list with children is modeled as one note part with indentation 1 followed by note parts with indentation 2, for example. - `name` (string, optional) - `type`: `code` (code) - `indentation` (integer, optional, default: 0) — All notes have an indentation level - the default is 0 for no indent. For lists, indentation gives notes hierarchy - a bulleted list with children is modeled as one note part with indentation 1 followed by note parts with indentation 2, for example. - `links` (list of EntryLink, optional) — Array of links referenced in text via an @-mention, hyperlink, or the drag-n-dropped preview attached to the note. - `text` (string, optional) — The textual contents of the note. - `type`: `external_file` (external_file) - `externalFileId` (string, optional) — The ID of the external file. Use the 'Get an external file' endpoint to retrieve metadata about it. - `indentation` (integer, optional, default: 0) — All notes have an indentation level - the default is 0 for no indent. For lists, indentation gives notes hierarchy - a bulleted list with children is modeled as one note part with indentation 1 followed by note parts with indentation 2, for example. - `links` (list of EntryLink, optional) — Array of links referenced in the caption via an @-mention, hyperlink, or the drag-n-dropped preview attached to the note. - `text` (string, optional) — The caption of the file attachment. - `type`: `inventory_container_table` (inventory_container_table) - `apiId` (string, optional) - `columns` (list of StructuredTableColumnInfo, optional) - `destinationContainerSchemaId` (string, optional) - `indentation` (integer, optional, default: 0) — All notes have an indentation level - the default is 0 for no indent. For lists, indentation gives notes hierarchy - a bulleted list with children is modeled as one note part with indentation 1 followed by note parts with indentation 2, for example. - `mode` (enum, optional) - Allowed values: `create_and_fill`, `fill`, `update` - `name` (string, optional) - `type`: `inventory_plate_table` (inventory_plate_table) - `apiId` (string, optional) - `columns` (list of StructuredTableColumnInfo, optional) - `destinationPlateSchemaId` (string, optional, nullable) - `destinationWellSchemaId` (string, optional) - `indentation` (integer, optional, default: 0) — All notes have an indentation level - the default is 0 for no indent. For lists, indentation gives notes hierarchy - a bulleted list with children is modeled as one note part with indentation 1 followed by note parts with indentation 2, for example. - `mode` (enum, optional) - Allowed values: `create_and_fill`, `fill`, `update` - `name` (string, optional) - `type`: `list_bullet` (list_bullet) - `indentation` (integer, optional, default: 0) — All notes have an indentation level - the default is 0 for no indent. For lists, indentation gives notes hierarchy - a bulleted list with children is modeled as one note part with indentation 1 followed by note parts with indentation 2, for example. - `links` (list of EntryLink, optional) — Array of links referenced in text via an @-mention, hyperlink, or the drag-n-dropped preview attached to the note. - `text` (string, optional) — The textual contents of the note. - `type`: `list_checkbox` (list_checkbox) - `checked` (boolean, optional) — Indicates whether the checkbox is checked or not. - `indentation` (integer, optional, default: 0) — All notes have an indentation level - the default is 0 for no indent. For lists, indentation gives notes hierarchy - a bulleted list with children is modeled as one note part with indentation 1 followed by note parts with indentation 2, for example. - `links` (list of EntryLink, optional) — Array of links referenced in text via an @-mention, hyperlink, or the drag-n-dropped preview attached to the note. - `text` (string, optional) — The textual contents of the note. - `type`: `list_number` (list_number) - `indentation` (integer, optional, default: 0) — All notes have an indentation level - the default is 0 for no indent. For lists, indentation gives notes hierarchy - a bulleted list with children is modeled as one note part with indentation 1 followed by note parts with indentation 2, for example. - `links` (list of EntryLink, optional) — Array of links referenced in text via an @-mention, hyperlink, or the drag-n-dropped preview attached to the note. - `text` (string, optional) — The textual contents of the note. - `type`: `lookup_table` (lookup_table) - `apiId` (string, optional) - `columns` (list of StructuredTableColumnInfo, optional) - `name` (string, optional) - `type`: `mixture_prep_table` (mixture_prep_table) - `apiId` (string, optional) - `columns` (list of StructuredTableColumnInfo, optional) - `indentation` (integer, optional, default: 0) — All notes have an indentation level - the default is 0 for no indent. For lists, indentation gives notes hierarchy - a bulleted list with children is modeled as one note part with indentation 1 followed by note parts with indentation 2, for example. - `mixtureSchemaId` (string, optional) - `name` (string, optional) - `type`: `note_linked_chart` (note_linked_chart) - `chart` (ChartNotePartChart, optional) — The full configuration for the chart to be displayed in-line in this note part. - `indentation` (integer, optional, default: 0) — All notes have an indentation level - the default is 0 for no indent. For lists, indentation gives notes hierarchy - a bulleted list with children is modeled as one note part with indentation 1 followed by note parts with indentation 2, for example. - `type`: `plate_creation_table` (plate_creation_table) - `apiId` (string, optional) - `columns` (list of StructuredTableColumnInfo, optional) - `indentation` (integer, optional, default: 0) — All notes have an indentation level - the default is 0 for no indent. For lists, indentation gives notes hierarchy - a bulleted list with children is modeled as one note part with indentation 1 followed by note parts with indentation 2, for example. - `name` (string, optional) - `plateSchemaId` (string, optional) - `type`: `registration_table` (registration_table) - `apiId` (string, optional) - `columns` (list of StructuredTableColumnInfo, optional) - `entitySchemaId` (string, optional) - `indentation` (integer, optional, default: 0) — All notes have an indentation level - the default is 0 for no indent. For lists, indentation gives notes hierarchy - a bulleted list with children is modeled as one note part with indentation 1 followed by note parts with indentation 2, for example. - `name` (string, optional) - `type`: `results_table` (results_table) - `apiId` (string, optional) - `assayResultSchemaId` (string, optional) - `columns` (list of StructuredTableColumnInfo, optional) - `indentation` (integer, optional, default: 0) — All notes have an indentation level - the default is 0 for no indent. For lists, indentation gives notes hierarchy - a bulleted list with children is modeled as one note part with indentation 1 followed by note parts with indentation 2, for example. - `name` (string, optional) - `type`: `table` (table) - `indentation` (integer, optional, default: 0) — All notes have an indentation level - the default is 0 for no indent. For lists, indentation gives notes hierarchy - a bulleted list with children is modeled as one note part with indentation 1 followed by note parts with indentation 2, for example. - `links` (list of EntryLink, optional) — Array of links referenced in the caption via an @-mention, hyperlink, or the drag-n-dropped preview attached to the note. - `table` (EntryTable, optional) — Actual tabular data with rows and columns of text on the note. - `text` (string, optional) — The caption of the table. - `type`: `text` (text) - `indentation` (integer, optional, default: 0) — All notes have an indentation level - the default is 0 for no indent. For lists, indentation gives notes hierarchy - a bulleted list with children is modeled as one note part with indentation 1 followed by note parts with indentation 2, for example. - `links` (list of EntryLink, optional) — Array of links referenced in text via an @-mention, hyperlink, or the drag-n-dropped preview attached to the note. - `text` (string, optional) — The textual contents of the note. - `type`: `text_box` (text_box) - `indentation` (integer, optional, default: 0) — All notes have an indentation level - the default is 0 for no indent. For lists, indentation gives notes hierarchy - a bulleted list with children is modeled as one note part with indentation 1 followed by note parts with indentation 2, for example. - `links` (list of EntryLink, optional) — Array of links referenced via an @-mention, hyperlink, or the drag-n-dropped preview attached to the note. - `name` (string, optional) - `text` (string, optional) ### ReviewChange - `action` (enum, optional) — The action which was performed with this change - Allowed values: `SEND_FOR_REVIEW`, `ACCEPT`, `REJECT`, `COMMENT`, `RETRACT` - `comment` (string, optional, nullable) — The comment which was left when the Review Change was submitted - `createdAt` (datetime, optional) — DateTime the Review Change was created at - `esigned` (boolean, optional) — Was the action verified through an e-signature compliant step - `id` (string, optional) - `reviewSnapshot` (ReviewSnapshot, optional, nullable) — Review Snapshot generated from this Review Change ### EntryReviewProcess - `completionStatus` (enum, optional) — State of the Entry at the end of the Review Process - Allowed values: `APPROVED`, `COMPLETED`, `ACCEPTED`, `REVIEWED`, `WITNESSED`, `SELF_REVIEWED` - `id` (string, optional) — ID of the Review Process - `name` (string, optional) — Name of the Review Process - `stages` (list of EntryReviewProcessStagesItems, optional) — Array of Stages for the Review Process - `type` (enum, optional) — Type of the Review Process - Allowed values: `SELF_REVIEW`, `SEQUENTIAL`, `PARALLEL` ### StructuredTableColumnInfo - `columnId` (string, optional) - `isReadOnly` (boolean, optional) - `name` (string, optional) ### EntryLink Links are contained within notes to reference resources that live outside of the entry. A link can target an external resource via an http(s):// hyperlink or a Benchling resource via @-mentions and drag-n-drop. - `id` (string, optional) — For linked Benchling resources, this will be the ID of that resource (e.g., 'seq_RhYGVnHF'). Omitted for "link" types. - `type` (enum, optional) — The type of resource being linked. For hyperlinks: 'link'. For linked Benchling resources, one of: 'user', 'request', 'entry', 'stage_entry', 'protocol', 'workflow', 'custom_entity', 'aa_sequence', 'dna_sequence', 'batch', 'box', 'container', 'location', 'plate', 'sql_dashboard'; and (for legacy support) 'insights_dashboard', 'folder'. - Allowed values: `link`, `user`, `request`, `entry`, `stage_entry`, `protocol`, `workflow`, `custom_entity`, `aa_sequence`, `dna_sequence`, `batch`, `box`, `container`, `location`, `plate`, `insights_dashboard`, `folder`, `sql_dashboard` - `webURL` (string, optional, nullable) — Canonical URL of the linked Benchling resource (if you have at least READ authorization for that resource), or the explicit URL provided as hyperlink for "link" types. Note: locations do not currently have a URL. ### ChartNotePartChart The full configuration for the chart to be displayed in-line in this note part. - `id` (string, optional) — The API identifier for this Analysis Chart. ### EntryTable Actual tabular data with rows and columns of text on the note. - `columnLabels` (list of string, optional) — Array of strings, with one item per column. Defaults to null, if the user is using the default, but is set if the user has given a custom name to the column. - `name` (string, optional) — Name of the table - defaults to e.g. Table1 but can be renamed. - `rows` (list of EntryTableRow, optional) — Array of row objects. ### ReviewSnapshot - `createdAt` (datetime, optional) — DateTime the Review Snapshot was created at - `downloadURL` (string, optional) — A short-lived URL that can be used to download the original file. - `expiresAt` (datetime, optional) — DateTime the downloadURL expires. - `size` (integer, optional) — Size, in bytes, of the snapshot file - `status` (enum, optional) — the current status of the Snapshot process - Allowed values: `PENDING`, `RUNNING`, `SUCCEEDED`, `FAILED` ### EntryReviewProcessStagesItems - `actionLabel` (enum, optional) — Action reviewer is doing during the review - Allowed values: `APPROVE`, `COMPLETE`, `ACCEPT`, `REVIEW`, `WITNESS`, `SELF_REVIEW` - `id` (string, optional) — ID of the Review Stage - `name` (string, optional) — Name of the Review Stage - `reviewers` (list of EntryReviewProcessStagesItemsReviewersItems, optional) — Reviewers for the Review Stage ### EntryTableRow Each has property 'cells' that is an array of cell objects - `cells` (list of EntryTableCell, optional) ### EntryReviewProcessStagesItemsReviewersItems - `handle` (string, optional) - `id` (string, optional) - `name` (string, optional) - `status` (enum, optional) — Status of the Reviewer - Allowed values: `BLOCKED`, `PENDING`, `FINISHED`, `REJECTED` ### EntryTableCell - `link` (EntryLink, optional) — A Link Resource if this cell contained a hyperlink. Otherwise, link will be omitted from the cell object. (Note: inventory and user types are not yet supported.) - `text` (string, optional) — The textual content of the cell. If the cell was originally a formula, this will be the evaluated version of the formula. ## Examples **Request** ```json { "folderId": "string", "name": "string" } ``` **Response** ```json { "apiURL": "https://benchling.com/api/v2/entries/etr_tv7m7B78", "archiveRecord": { "reason": "Made in error" }, "assignedReviewers": [ { "handle": "string", "id": "string", "name": "string" } ], "authors": [ { "handle": "string", "id": "string", "name": "string" } ], "createdAt": "2024-01-15T09:30:00Z", "creator": { "handle": "string", "id": "string", "name": "string" }, "customFields": { "Legacy ID": { "value": "STR100" } }, "days": [ { "date": "string", "notes": [ { "type": "text", "indentation": 0, "links": [ { "id": "string", "type": "link", "webURL": "string" } ], "text": "string" } ], "title": "string" } ], "displayId": "string", "entryTemplateId": "string", "fields": {}, "folderId": "string", "id": "string", "modifiedAt": "string", "name": "string", "reviewRecord": { "comment": "string", "reviewChanges": [ { "action": "SEND_FOR_REVIEW", "comment": "string", "createdAt": "2024-01-15T09:30:00Z", "esigned": true, "id": "string", "reviewSnapshot": { "createdAt": "2024-01-15T09:30:00Z", "downloadURL": "string", "expiresAt": "2024-01-15T09:30:00Z", "size": 1, "status": "PENDING" } } ], "reviewProcesses": [ { "completionStatus": "APPROVED", "id": "string", "name": "string", "stages": [ { "actionLabel": "APPROVE", "id": "string", "name": "string", "reviewers": [ { "handle": "string", "id": "string", "name": "string", "status": "BLOCKED" } ] } ], "type": "SELF_REVIEW" } ], "status": "ACCEPTED" }, "schema": { "id": "string", "modifiedAt": "2017-04-18T05:55:48.685345+00:00", "name": "string" }, "webURL": "string" } ``` **SDK Code** ```python import requests url = "https://{tenant_name}.benchling.com/api/v2/entries" payload = { "folderId": "string", "name": "string" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://{tenant_name}.benchling.com/api/v2/entries'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"folderId":"string","name":"string"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ```