Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
title: Benchling AA Sequences Entries API
version: 2.0.0
description: 'AA Sequences are the working units of cells that make everything run (they help make structures, catalyze reactions and allow for signaling - a kind of internal cell communication). On Benchling, these are comprised of a string of amino acids and collections of other attributes, such as annotations.
'
servers:
- url: /api/v2
security:
- oAuth: []
- basicApiKeyAuth: []
tags:
- description: Entries are rich text documents that allow you to capture all of your experimental data in one place.
name: Entries
paths:
/entries:
get:
description: List notebook entries
operationId: listEntries
parameters:
- description: Number of results to return. Defaults to 50, maximum of 100.
in: query
name: pageSize
schema:
default: 50
maximum: 100
minimum: 0
type: integer
- description: Token for pagination
in: query
name: nextToken
schema:
type: string
- description: 'Method by which to order search results. Valid sorts are modifiedAt (modified time, most recent first) and name (entity name, alphabetical). Optionally add :asc or :desc to specify ascending or descending order.
'
in: query
name: sort
schema:
default: modifiedAt:desc
enum:
- createdAt
- createdAt:asc
- createdAt:desc
- modifiedAt
- modifiedAt:asc
- modifiedAt:desc
- name
- name:asc
- name:desc
type: string
- description: 'Datetime, in RFC 3339 format. Supports the > and < operators. Time zone defaults to UTC. Restricts results to those modified in the specified range. e.g. > 2017-04-30. Date ranges can be specified with the following nomenclature > YYYY-MM-DD AND <YYYY-MM-DD.
'
examples:
and-range:
summary: Filter for all models modified within a certain range using the AND operator.
value: '> 2022-03-01 AND < 2022-04-01'
full-rfc-3339-format:
summary: Filter for modified models using the full RFC 3339 format
value: '> 2020-12-31T21:07:14-05:00'
greater-than-example:
summary: Filter for all models modified after a certain date
value: '> 2022-03-01'
in: query
name: modifiedAt
schema:
type: string
- description: Name of an Entry. Restricts results to those with the specified name.
in: query
name: name
schema:
type: string
- description: ID of a project. Restricts results to those in the project.
in: query
name: projectId
schema:
type: string
- description: 'Archive reason. Restricts items to those with the specified archive reason. Use "NOT_ARCHIVED" to filter for unarchived entries. Use "ANY_ARCHIVED" to filter for archived entries regardless of reason. Use "ANY_ARCHIVED_OR_NOT_ARCHIVED" to return items for both archived and unarchived.
'
examples:
1_not_archived:
summary: Only include unarchived items (default).
value: NOT_ARCHIVED
2_archived_reason:
summary: Includes items archived for a specific reason.
value: Retired
3_any_archived:
summary: Includes items archived for any reason.
value: ANY_ARCHIVED
4_any_archived_or_not_archived:
summary: Includes both archived and unarchived items.
value: ANY_ARCHIVED_OR_NOT_ARCHIVED
in: query
name: archiveReason
schema:
type: string
- description: 'Restrict results to those with the given review status. Supported statuses: IN_PROGRESS, ACCEPTED, REJECTED, NEEDS_REVIEW, RETRACTED
'
in: query
name: reviewStatus
schema:
enum:
- IN_PROGRESS
- ACCEPTED
- REJECTED
- NEEDS_REVIEW
- RETRACTED
type: string
- description: 'Comma-separated list of entry IDs. Restricts results to those mentioned within the entries in this list.
'
in: query
name: mentionedIn
schema:
type: string
- description: 'Comma-separated list of resource IDs. Restricts results to entries that mention the given items.
'
in: query
name: mentions
schema:
type: string
- description: 'Comma-separated list of ids. Matches all of the provided IDs, or returns a 400 error that includes a list of which IDs are invalid.
'
in: query
name: ids
schema:
type: string
- description: 'ID of a schema. Restricts results to those of the specified schema.
'
in: query
name: schemaId
schema:
type: string
- description: 'Comma-separated list of names. Maximum of 100. Restricts results to those that match any of the specified names, case insensitive. Warning - this filter can be non-performant due to case insensitivity.
'
in: query
name: names.anyOf
schema:
example: MyName1,MyName2
type: string
- description: 'Comma-separated list of names. Maximum of 100. Restricts results to those that match any of the specified names, case sensitive.
'
in: query
name: names.anyOf.caseSensitive
schema:
example: MyName1,MyName2
type: string
- description: Comma-separated list of ids. Restricts results to entries that have assignees of any of the specified ids.
in: query
name: assignedReviewerIds.anyOf
schema:
example: ent_a0SApq3z,ent_SdUvia1v
type: string
- description: Comma separated list of users IDs.
in: query
name: creatorIds
schema:
example: ent_a0SApq3z
type: string
- description: Comma separated list of user or app IDs. Maximum of 100.
in: query
name: authorIds.anyOf
schema:
example: ent_a0SApq3z,ent_b4AApz9b
type: string
- description: Comma-separated list of Entry Display IDs.
in: query
name: displayIds
schema:
example: VPR001,VPR002
type: string
- description: 'Comma-separated list of fields to return. Modifies the output shape. To return all keys at a given level, enumerate them or use the wildcard, ''*''. For more information, [click here](https://docs.benchling.com/docs/getting-started-1#returning-query-parameter).
**Note:** "entries.days.notes" cannot be introspected with the returning parameter, and any sub fields will be ignored. E.g., "entries.days.notes.text" will return the same model as "entries.days.notes".
'
in: query
name: returning
schema:
example: entries.id, entries.name, entries.modifiedAt
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EntriesPaginatedList'
description: 'Returns a list of entries. Entries are notes that users can take. They''re organized by "days" (which are user-configurable) and modeled within each day as a list of "notes." Each note has a type - the simplest is a "text" type, but lists, tables, and external files are also supported.
*Note:* the current Entry resource has a few limitations:
- Formatting information is not yet supported. Header formatting, bolding, and other stylistic information is not presented.
- Data in tables is presented as text always - numeric values will need to be parsed into floats or integers, as appropriate.
Note: Data in Results tables are not accessible through this API call. Results table data can be called through the Results API calls.
'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: List entries
tags:
- Entries
post:
description: Create a notebook entry
operationId: createEntry
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EntryCreate'
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Entry'
description: Created
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Create a notebook entry
tags:
- Entries
/entries/{entry_id}:
get:
description: Get a notebook entry by ID
operationId: getEntry
parameters:
- description: ID of the entry
in: path
name: entry_id
required: true
schema:
type: string
- description: 'Comma-separated list of fields to return. Modifies the output shape. To return all keys at a given level, enumerate them or use the wildcard, ''*''. For more information, [click here](https://docs.benchling.com/docs/getting-started-1#returning-query-parameter).
**Note:** "days.notes" cannot be introspected with the returning parameter, and any sub fields will be ignored. E.g., "days.notes.text" will return the same model as "days.notes".
'
in: query
name: returning
schema:
example: id, name, modifiedAt
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EntryById'
description: 'Returns a single entry. Entries are notes that users can take. They''re organized by "days" (which are user-configurable) and modeled within each day as a list of "notes." Each note has a type - the simplest is a "text" type, but lists, tables, and external files are also supported.
*Note:* the current Entry resource has a few limitations:
- Formatting information is not yet supported. Header formatting, bolding, and other stylistic information is not presented.
- Data in tables is presented as text always - numeric values will need to be parsed into floats or integers, as appropriate.
Note: Data in Results tables are not accessible through this API call. Results table data can be called through the Results API calls.
'
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
description: Not Found
summary: Get a notebook entry by ID
tags:
- Entries
patch:
description: Update a notebook entry's metadata
operationId: updateEntry
parameters:
- description: ID of the entry
in: path
name: entry_id
required: true
schema:
type: string
- description: 'Comma-separated list of fields to return. Modifies the output shape. To return all keys at a given level, enumerate them or use the wildcard, ''*''. For more information, [click here](https://docs.benchling.com/docs/getting-started-1#returning-query-parameter).
**Note:** "days.notes" cannot be introspected with the returning parameter, and any sub fields will be ignored. E.g., "days.notes.text" will return the same model as "days.notes".
'
in: query
name: returning
schema:
example: id, name, modifiedAt
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EntryUpdate'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Entry'
description: OK
summary: Update a notebook entry's metadata
tags:
- Entries
/entries/{entry_id}/external-files/{external_file_id}:
get:
description: 'Retrieves the metadata for an external file. Use the ''downloadURL'' to download the actual file. (Expand the schema view for details)
'
operationId: getExternalFileMetadata
parameters:
- description: ID of the entry the file was uploaded to
in: path
name: entry_id
required: true
schema:
type: string
- description: ID of the external file
in: path
name: external_file_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EntryExternalFileById'
description: OK
summary: 'Retrieves the metadata for an external file. Use the ''downloadURL'' to download the actual file.
'
tags:
- Entries
/entries:archive:
post:
description: Archive notebook entries
operationId: archiveEntries
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EntriesArchive'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EntriesArchivalChange'
description: OK
summary: Archive notebook entries
tags:
- Entries
/entries:bulk-get:
get:
description: Get notebook entries using entry IDs or display IDs
operationId: bulkGetEntries
parameters:
- description: Comma-separated list of Entry IDs.
in: query
name: entryIds
schema:
type: string
- description: Comma-separated list of Entry Display IDs.
in: query
name: displayIds
schema:
type: string
- description: 'Comma-separated list of fields to return. Modifies the output shape. To return all keys at a given level, enumerate them or use the wildcard, ''*''. For more information, [click here](https://docs.benchling.com/docs/getting-started-1#returning-query-parameter).
**Note:** "entries.days.notes" cannot be introspected with the returning parameter, and any sub fields will be ignored. E.g., "entries.days.notes.text" will return the same model as "entries.days.notes".
'
in: query
name: returning
schema:
example: entries.id, entries.name, entries.modifiedAt
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Entries'
description: 'Returns a list of entries. Entries are notes that users can take. They''re organized by "days" (which are user-configurable) and modeled within each day as a list of "notes." Each note has a type - the simplest is a "text" type, but lists, tables, and external files are also supported.
*Note:* the current Entry resource has a few limitations:
- Formatting information is not yet supported. Header formatting, bolding, and other stylistic information is not presented.
- Data in tables is presented as text always - numeric values will need to be parsed into floats or integers, as appropriate.
Note: Data in Results tables are not accessible through this API call. Results table data can be called through the Results API calls.
'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Get notebook entries using entry IDs or display IDs
tags:
- Entries
/entries:unarchive:
post:
description: Unarchive notebook entries
operationId: unarchiveEntries
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EntriesUnarchive'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EntriesArchivalChange'
description: OK
summary: Unarchive notebook entries
tags:
- Entries
/entry-templates:
get:
description: List entry templates
operationId: listEntryTemplates
parameters:
- description: Number of results to return. Defaults to 50, maximum of 100.
in: query
name: pageSize
schema:
default: 50
maximum: 100
minimum: 0
type: integer
- description: Token for pagination
in: query
name: nextToken
schema:
type: string
- description: 'Datetime, in RFC 3339 format. Supports the > and < operators. Time zone defaults to UTC. Restricts results to those modified in the specified range. e.g. > 2017-04-30. Date ranges can be specified with the following nomenclature > YYYY-MM-DD AND <YYYY-MM-DD.
'
examples:
and-range:
summary: Filter for all models modified within a certain range using the AND operator.
value: '> 2022-03-01 AND < 2022-04-01'
full-rfc-3339-format:
summary: Filter for modified models using the full RFC 3339 format
value: '> 2020-12-31T21:07:14-05:00'
greater-than-example:
summary: Filter for all models modified after a certain date
value: '> 2022-03-01'
in: query
name: modifiedAt
schema:
type: string
- description: Name of an Entry Template. Restricts results to those with the specified name.
in: query
name: name
schema:
type: string
- description: 'ID of a template collection. Resticts results to those in the template collection.
'
in: query
name: templateCollectionId
schema:
example: tmplcol_jC7rOniv
type: string
- description: 'Comma-separated list of ids. Matches all of the provided IDs, or returns a 400 error that includes a list of which IDs are invalid.
'
in: query
name: ids
schema:
type: string
- description: 'ID of a schema. Restricts results to those of the specified schema.
'
in: query
name: schemaId
schema:
type: string
- description: 'Comma-separated list of fields to return. Modifies the output shape. To return all keys at a given level, enumerate them or use the wildcard, ''*''. For more information, [click here](https://docs.benchling.com/docs/getting-started-1#returning-query-parameter).
**Note:** "entryTemplates.days.notes" cannot be introspected with the returning parameter, and any sub fields will be ignored. E.g., "entryTemplates.days.notes.text" will return the same model as "entryTemplates.days.notes".
'
in: query
name: returning
schema:
example: entryTemplates.id,entryTemplates.modifiedAt
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EntryTemplatesPaginatedList'
description: 'Returns a list of entry templates. Entry templates are templates that users can base new notebook entries off of.
'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: List entry templates
tags:
- Entries
/entry-templates/{entry_template_id}:
get:
description: Get a notebook template entry by ID
operationId: getEntryTemplate
parameters:
- description: ID of the entry template
in: path
name: entry_template_id
required: true
schema:
type: string
- description: 'Comma-separated list of fields to return. Modifies the output shape. To return all keys at a given level, enumerate them or use the wildcard, ''*''. For more information, [click here](https://docs.benchling.com/docs/getting-started-1#returning-query-parameter).
**Note:** "days.notes" cannot be introspected with the returning parameter, and any sub fields will be ignored. E.g., "days.notes.text" will return the same model as "days.notes".
'
in: query
name: returning
schema:
example: id,modifiedAt
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EntryTemplate'
description: 'Returns a single entry template. Entry templates are templates that users can base new notebook entries off of.
'
summary: Get a notebook template entry by ID
tags:
- Entries
patch:
description: Update a notebook template entry's metadata
operationId: updateEntryTemplate
parameters:
- description: ID of the template entry
in: path
name: entry_template_id
required: true
schema:
type: string
- description: 'Comma-separated list of fields to return. Modifies the output shape. To return all keys at a given level, enumerate them or use the wildcard, ''*''. For more information, [click here](https://docs.benchling.com/docs/getting-started-1#returning-query-parameter).
**Note:** "days.notes" cannot be introspected with the returning parameter, and any sub fields will be ignored. E.g., "days.notes.text" will return the same model as "days.notes".
'
in: query
name: returning
schema:
example: id, name, modifiedAt
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EntryTemplateUpdate'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EntryTemplate'
description: OK
summary: Update a notebook template entry's metadata
tags:
- Entries
components:
schemas:
ResultsTableNotePart:
allOf:
- $ref: '#/components/schemas/BaseNotePart'
- $ref: '#/components/schemas/StructuredTableApiIdentifiers'
- properties:
assayResultSchemaId:
example: assaysch_msh1Ly6g
type: string
type:
enum:
- results_table
type: string
type: object
AssayRunNotePart:
allOf:
- $ref: '#/components/schemas/BaseNotePart'
- properties:
assayRunId:
example: 588aca02-1a20-4b94-a40f-b3f3a0081749
type:
- string
- 'null'
assayRunSchemaId:
example: assaysch_msh1Ly6g
type: string
type:
enum:
- assay_run
type: string
type: object
EntryTableRow:
description: Each has property 'cells' that is an array of cell objects
properties:
cells:
items:
$ref: '#/components/schemas/EntryTableCell'
type: array
type: object
ExternalFileNotePart:
allOf:
- $ref: '#/components/schemas/BaseNotePart'
- properties:
externalFileId:
description: 'The ID of the external file. Use the ''Get an external file'' endpoint to retrieve metadata about it.
'
type: string
links:
description: 'Array of links referenced in the caption via an @-mention, hyperlink, or the drag-n-dropped preview attached to the note.
'
items:
$ref: '#/components/schemas/EntryLink'
type: array
text:
description: The caption of the file attachment.
type: string
type:
enum:
- external_file
type: string
type: object
description: An attached user-uploaded file
LookupTableNotePart:
allOf:
- $ref: '#/components/schemas/StructuredTableApiIdentifiers'
- properties:
type:
enum:
- lookup_table
type: string
type: object
EntryTemplatesPaginatedList:
additionalProperties: false
properties:
entryTemplates:
items:
$ref: '#/components/schemas/EntryTemplate'
type: array
nextToken:
type: string
type: object
EntriesPaginatedList:
properties:
entries:
items:
$ref: '#/components/schemas/Entry'
type: array
nextToken:
type: string
type: object
FieldType:
enum:
- 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
type: string
Fields:
additionalProperties:
$ref: '#/components/schemas/Field'
type: object
StructuredTableApiIdentifiers:
properties:
apiId:
type: string
columns:
items:
$ref: '#/components/schemas/StructuredTableColumnInfo'
type: array
name:
type: string
type: object
StructuredTableColumnInfo:
properties:
columnId:
type: string
isReadOnly:
type: boolean
name:
type: string
type: object
TableNotePart:
allOf:
- $ref: '#/components/schemas/BaseNotePart'
- properties:
links:
description: 'Array of links referenced in the caption via an @-mention, hyperlink, or the drag-n-dropped preview attached to the note.
'
items:
$ref: '#/components/schemas/EntryLink'
type: array
table:
allOf:
- $ref: '#/components/schemas/EntryTable'
type: object
text:
description: The caption of the table.
type: string
type:
enum:
- table
type: string
type: object
description: A table with rows and columns of text
MixturePrepTableNotePart:
allOf:
- $ref: '#/components/schemas/BaseNotePart'
- $ref: '#/components/schemas/StructuredTableApiIdentifiers'
- properties:
mixtureSchemaId:
example: ts_eGNPfqCX
type: string
type:
enum:
- mixture_prep_table
type: string
type: object
ChartNotePart:
allOf:
- $ref: '#/components/schemas/BaseNotePart'
- properties:
chart:
description: The full configuration for the chart to be displayed in-line in this note part.
properties:
id:
description: The API identifier for this Analysis Chart.
type: string
type: object
type:
enum:
- note_linked_chart
type: string
type: object
EntryLink:
description: '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.
'
properties:
id:
description: 'For linked Benchling resources, this will be the ID of that resource (e.g., ''seq_RhYGVnHF''). Omitted for "link" types.
'
type: string
type:
description: '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''.
'
enum:
- link
- user
- request
- entry
- stage_entry
- protocol
- workflow
- custom_entity
- aa_sequence
- dna_sequence
- batch
- box
- container
- location
- plate
- insights_dashboard
- folder
- sql_dashboard
type: string
webURL:
description: '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.
'
type:
- string
- 'null'
type: object
BadRequestError:
properties:
error:
allOf:
- $ref: '#/components/schemas/BaseError'
- properties:
type:
enum:
- invalid_request_error
type: string
type: object
EntryById:
properties:
entry:
$ref: '#/components/schemas/Entry'
type: object
EntryTemplate:
additionalProperties: false
description: 'Entry templates are templates that users can base new notebook entries off of.
'
properties:
apiURL:
description: The canonical url of the Entry Template in the API.
example: https://benchling.com/api/v2/entry-templates/tmpl_tv7m7B78
format: uri
readOnly: true
type: string
createdAt:
description: DateTime the template was created at
format: date-time
readOnly: true
type: string
creator:
allOf:
- $ref: '#/components/schemas/UserSummary'
description: UserSummary Resource of the user who created the template
readOnly: true
customFields:
$ref: '#/components/schemas/CustomFields'
days:
description: 'Array of day objects. Each day object has a day index (integer) and notes field (array of notes, expand further for details on note types).
'
items:
$ref: '#/components/schemas/EntryTemplateDay'
type: array
fields:
$ref: '#/components/schemas/Fields'
id:
description: ID of the entry template
type: string
modifiedAt:
description: DateTime the template was last modified
type: string
name:
description: Title of the template
type: string
schema:
allOf:
- $ref: '#/components/schemas/EntrySchema'
description: Entry schema if set
title: SchemaProperty
type:
- object
- 'null'
templateCollectionId:
description: ID of the collection that contains the template
type: string
webURL:
description: URL of the template
type: string
type: object
CustomField:
properties:
value:
type: string
type: object
InventoryPlateTableNotePart:
allOf:
- $ref: '#/components/schemas/BaseNotePart'
- $ref: '#/components/schemas/StructuredTableApiIdentifiers'
- properties:
destinationPlateSchemaId:
example: pltsch_LRIuH0yJ
type:
- string
- 'null'
destinationWellSchemaId:
example: consch_JEL0WC
# --- truncated at 32 KB (58 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/benchling/refs/heads/main/openapi/benchling-entries-api-openapi.yml