Skip to navigation

Working with Entries

Entries are the core document type in Benchling's Electronic Lab Notebook. This guide covers reading an entry's content, creating an entry with initial content, and submitting content edits with partsMutation.

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

GET /api/v3/entry/etr_8rVKW0g7

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

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.
POST /api/v3/entry

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.
PATCH /api/v3/entry/etr_8rVKW0g7

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