> 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.

# Working with Entries

> **Info**
>
> ### Beta APIs
>
> The Document APIs are beta. Send the `EARLY-ACCESS: true` header on every request shown here; without it these endpoints are unavailable. See [Introduction to Documents](/docs/introduction-to-documents) and the [Stability Guidelines](/docs/stability-guidelines).

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.

**`Endpoint`**

```text title="Endpoint"
GET /api/v3/entry/etr_8rVKW0g7
```

**`Example Response`**

```json title="Example Response"
{
  "id": "etr_8rVKW0g7",
  "name": "Protein Concentration Assay 2025-01-15",
  "displayId": "EXP-2025-0042",
  "createdAt": "2025-01-15T10:30:00Z",
  "modifiedAt": "2025-01-15T15:00:00Z",
  "archived": false,
  "folder": {
    "id": "lib_abc123"
  },
  "schema": {
    "id": "entsch_x9Kp2mQ4"
  },
  "versionMetadata": {
    "versionId": "etrver_Ax7b2kR9",
    "createdAt": "2025-01-15T15:00: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.

**`Endpoint`**

```text title="Endpoint"
GET /api/v3/entry/etr_8rVKW0g7/parts/items
```

**`Example Response`**

```json title="Example Response"
{
  "items": [
    {
      "__typename": "DocumentPartSection",
      "id": "docpart_Qm3nW8x1",
      "modifiedAt": "2025-01-15T10:30:00Z",
      "versionMetadata": { "versionId": "etrver_Ax7b2kR9", "createdAt": "2025-01-15T15:00:00Z" },
      "title": "Results",
      "date": "2025-01-15",
      "color": null
    },
    {
      "__typename": "DocumentPartHeader",
      "id": "docpart_Kp9vR2y4",
      "modifiedAt": "2025-01-15T14:22:00Z",
      "versionMetadata": { "versionId": "etrver_Ax7b2kR9", "createdAt": "2025-01-15T15:00:00Z" },
      "headerType": "HEADER_1",
      "text": "Experiment Results",
      "formats": [],
      "links": [],
      "mentions": [],
      "indentation": 0
    },
    {
      "__typename": "DocumentPartText",
      "id": "docpart_Xt5bJ7z3",
      "modifiedAt": "2025-01-15T14:22:00Z",
      "versionMetadata": { "versionId": "etrver_Ax7b2kR9", "createdAt": "2025-01-15T15:00:00Z" },
      "text": "The following data was collected on 2025-01-15.",
      "formats": [],
      "links": [],
      "mentions": [],
      "indentation": 0
    },
    {
      "__typename": "DocumentPartUnstructuredTable",
      "id": "docpart_Nw4mP1a8",
      "modifiedAt": "2025-01-15T14:22:00Z",
      "versionMetadata": { "versionId": "etrver_Ax7b2kR9", "createdAt": "2025-01-15T15:00:00Z" },
      "name": "Concentration Measurements",
      "caption": null,
      "columnDefinitions": [
        { "name": "Sample" },
        { "name": "Concentration (mg/mL)" }
      ],
      "rowCount": 3,
      "rows": "https://benchling.com/api/v3/document-part-unstructured-table/docpart_Nw4mP1a8/rows/items",
      "isEvaluated": false,
      "indentation": 0
    },
    {
      "__typename": "DocumentPartAttachment",
      "id": "docpart_Fg7hL2m9",
      "modifiedAt": "2025-01-15T15:00:00Z",
      "versionMetadata": { "versionId": "etrver_Ax7b2kR9", "createdAt": "2025-01-15T15:00:00Z" },
      "externalFileId": "efl_RkQ2Xp7m",
      "filename": "western_blot_day3.tif",
      "download": {
        "url": "https://s3.amazonaws.com/benchling-attachments/...?X-Amz-Expires=3600&...",
        "expiresAt": "2025-01-15T16:00:00Z"
      },
      "scanStatus": "NO_THREATS_FOUND",
      "size": 2097152,
      "caption": null,
      "customWidth": null,
      "indentation": 0
    }
  ],
  "nextToken": ""
}
```

Each document part in the response contains:

* `__typename`: The type of the document part, such as `DocumentPartSection`, `DocumentPartHeader`, `DocumentPartText`, `DocumentPartUnstructuredTable`, or `DocumentPartAttachment`. The part's content fields, such as `text` or `title`, sit at the top level of the part alongside `id`, and depend on its type.
* `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.
* `versionMetadata.versionId`: The current version of the entry that contains the part.

For some part types like tables, the listing returns 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}/rows/items`.

## 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.

**`Endpoint`**

```text title="Endpoint"
POST /api/v3/entry
```

**`Example Request`**

```json title="Example Request"
{
  "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. For `insert`, these are `position` and `parts`. `position` is `beginning_of_document`, `end_of_document`, or a document part ID to insert immediately before that part.

**`Endpoint`**

```text title="Endpoint"
PATCH /api/v3/entry/etr_8rVKW0g7
```

**`Example Request`**

```json title="Example Request"
{
  "partsMutation": {
    "operationType": "insert",
    "version": "etrver_Ax7b2kR9",
    "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.