Working with Entries

An entry is the core document type in Benchling's Electronic Lab Notebook (ELN).

You can use entries to record experimental work and observations. Entries organize content into sections such as text, tables, file attachments, and Results tables.

Entries have a few important properties:

Entries always require a leading section.
Entries can optionally conform to an Entry schema that defines custom fields you can complete on the entry.
You can create entries from scratch, from Benchling AI, or from an entry template.

Reading an entry's content

To read an entry, you must first acquire its ID. You can use the listing endpoint for this, or get it from Benchling or another API response. In our example below, the ID is etr_8rVKW0g7.

To read an entry and its content, first make a GET request to the top-level API.

GET /api/v3/entry/etr_8rVKW0g7

{
  "id": "etr_8rVKW0g7",
  "name": "Protein Concentration Assay 2025-01-15",
  "displayId": "EXP-2025-0042",
  "createdAt": "2025-01-15T10:30:00Z",
  "modifiedAt": "2025-01-15T14:22:00Z",
  "archived": false,
  "folder": {
    "id": "lib_abc123"
  },
  "schema": {
    "id": "entsch_x9Kp2mQ4"
  },
  "versionMetadata": {
    "versionId": "etrver_Ax7b2kR9",
    "createdAt": "2025-01-15T14:22:00Z"
  },
  "parts": "https://benchling.com/api/v3/entry/etr_8rVKW0g7/parts/items"
}

Key response fields:

id: The stable identifier of the entry.
name: The title of the entry.
versionMetadata.versionId: The current version identifier. You must include this value to submit edits.
parts: The URL of the document content listing endpoint for this entry.

To list the document content of the entry, paginate through the nested parts listing endpoint, using nextToken to retrieve subsequent pages.

GET /api/v3/entry/etr_8rVKW0g7/parts/items

{
  "items": [
    {
      "id": "docpart_Qm3nW8x1",
      "versionId": "etrver_Ax7b2kR9",
      "modifiedAt": "2025-01-15T10:30:00Z",
      "container": { "id": "etr_8rVKW0g7" },
      "content": {
        "__typename": "Benchling.SectionDocumentContent",
        "title": "Results",
        "date": "2025-01-15",
        "color": null
      }
    },
    {
      "id": "docpart_Kp9vR2y4",
      "versionId": "etrver_Ax7b2kR9",
      "modifiedAt": "2025-01-15T14:22:00Z",
      "container": { "id": "etr_8rVKW0g7" },
      "content": {
        "__typename": "Benchling.HeaderDocumentContent",
        "headerType": "HEADER_1",
        "text": "Experiment Results",
        "indentation": 0
      }
    },
    {
      "id": "docpart_Xt5bJ7z3",
      "versionId": "etrver_Ax7b2kR9",
      "modifiedAt": "2025-01-15T14:22:00Z",
      "container": { "id": "etr_8rVKW0g7" },
      "content": {
        "__typename": "Benchling.TextDocumentContent",
        "text": "The following data was collected on 2025-01-15.",
        "formats": [],
        "links": [],
        "mentions": [],
        "indentation": 0
      }
    },
    {
      "id": "docpart_Nw4mP1a8",
      "versionId": "etrver_Ax7b2kR9",
      "modifiedAt": "2025-01-15T14:22:00Z",
      "container": { "id": "etr_8rVKW0g7" },
      "content": {
        "__typename": "Benchling.UnstructuredTableDocumentContentSummary",
        "name": "Concentration Measurements",
        "columnCount": 2,
        "rowCount": 3
      }
    },
    {
      "id": "docpart_Fg7hL2m9",
      "versionId": "etrver_Ax7b2kR9",
      "modifiedAt": "2025-01-15T15:00:00Z",
      "container": { "id": "etr_8rVKW0g7" },
      "content": {
        "__typename": "Benchling.AttachmentDocumentContent",
        "externalFileId": "efl_RkQ2Xp7m",
        "filename": "western_blot_day3.tif",
        "downloadUrl": "https://s3.amazonaws.com/benchling-attachments/...?X-Amz-Expires=3600&...",
        "downloadUrlExpiresAt": "2025-01-15T16:00:00Z",
        "size": 2097152,
        "customWidth": null,
        "indentation": 0
      }
    }
  ],
  "nextToken": ""
}

Each document part in the response contains:

id: The stable identifier of the document part. This doesn't change across versions unless you remove or replace the part. Use it for absolute positioning when inserting or moving content, and for retrieving additional information such as table row data.
content: The content payload, discriminated by __typename. For some content types like tables this is a summary. Use the dedicated document part endpoints to retrieve the full data, such as table rows. For example: GET /api/v3/document-part-unstructured-table/{doc_part_id}.

Creating an entry with content

When creating an entry, you can declare initial document content by using the parts field.

This uses the same content input format as the insert operation in partsMutation, covered below. You're populating an empty document with an ordered list of content.

Because entries require a leading section, the first item in parts must be a section content input.

Key request fields:

name (required): The title of the entry.
folderId (required): The ID of the folder to create the entry in.
schemaId: An optional Entry schema to conform to.
parts: An optional list of ordered content (sections, text, tables, and so on) to populate the entry with.

POST /api/v3/entry

{
  "name": "Protein Concentration Assay 2025-01-15",
  "folderId": "lib_abc123",
  "parts": [
    {
      "contentType": "section",
      "title": "Results"
    },
    {
      "contentType": "header",
      "headerType": "HEADER_1",
      "text": "Experiment Results"
    },
    {
      "contentType": "text",
      "text": "The following data was collected on 2025-01-15."
    },
    {
      "contentType": "list_item",
      "listType": "BULLET",
      "text": "Sample A: 0.85 mg/mL"
    },
    {
      "contentType": "list_item",
      "listType": "BULLET",
      "text": "Sample B: 1.23 mg/mL"
    },
    {
      "contentType": "unstructured_table",
      "name": "Concentration Measurements",
      "columnDefinitions": [
        { "name": "Sample" },
        { "name": "Concentration (mg/mL)" }
      ],
      "rows": [
        { "cells": [{ "inputValue": { "type": "text_value", "value": "Sample A" } }, { "inputValue": { "type": "text_value", "value": "0.85" } }] },
        { "cells": [{ "inputValue": { "type": "text_value", "value": "Sample B" } }, { "inputValue": { "type": "text_value", "value": "1.23" } }] },
        { "cells": [{ "inputValue": { "type": "text_value", "value": "Sample C" } }, { "inputValue": { "type": "text_value", "value": "0.97" } }] }
      ]
    }
  ]
}

A successful creation request returns the created entry's ID and data.

Updating an entry's content

When updating an entry, you can change core metadata like its name or archive state by providing the desired values. Operating on the content, however, works differently. Instead of declaring the desired state, you declare a partsMutation.

Key request fields for partsMutation:

operationType (required): An insert, move, or delete operation.
version (required): The current version of the entry.
Operation-specific fields (coordinates, parts list, and so on).

PATCH /api/v3/entry/etr_8rVKW0g7

{
  "partsMutation": {
    "operationType": "insert",
    "version": "etrver_Ax7b2kR9",
    "coordinates": {
      "position": "end_of_document"
    },
    "parts": [
      {
        "contentType": "header",
        "headerType": "HEADER_1",
        "text": "Experiment Results"
      },
      {
        "contentType": "text",
        "text": "The following data was collected on 2025-01-15."
      },
      {
        "contentType": "list_item",
        "listType": "BULLET",
        "text": "Sample A: 0.85 mg/mL"
      },
      {
        "contentType": "list_item",
        "listType": "BULLET",
        "text": "Sample B: 1.23 mg/mL"
      },
      {
        "contentType": "unstructured_table",
        "name": "Concentration Measurements",
        "columnDefinitions": [
          { "name": "Sample" },
          { "name": "Concentration (mg/mL)" }
        ],
        "rows": [
          { "cells": [{ "inputValue": { "type": "text_value", "value": "Sample A" } }, { "inputValue": { "type": "text_value", "value": "0.85" } }] },
          { "cells": [{ "inputValue": { "type": "text_value", "value": "Sample B" } }, { "inputValue": { "type": "text_value", "value": "1.23" } }] },
          { "cells": [{ "inputValue": { "type": "text_value", "value": "Sample C" } }, { "inputValue": { "type": "text_value", "value": "0.97" } }] }
        ]
      }
    ]
  }
}

A successful edit request returns the entry's updated state.