openapi: 3.0.1
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
nullable: false
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
nullable: false
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
nullable: false
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:
ReviewSnapshot:
additionalProperties: false
properties:
createdAt:
description: DateTime the Review Snapshot was created at
format: date-time
type: string
downloadURL:
description: A short-lived URL that can be used to download the original file.
type: string
expiresAt:
description: DateTime the downloadURL expires.
format: date-time
type: string
size:
description: Size, in bytes, of the snapshot file
type: integer
status:
description: the current status of the Snapshot process
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
type: string
type: object
InventoryPlateTableNotePart:
allOf:
- $ref: '#/components/schemas/BaseNotePart'
- $ref: '#/components/schemas/StructuredTableApiIdentifiers'
- properties:
destinationPlateSchemaId:
example: pltsch_LRIuH0yJ
nullable: true
type: string
destinationWellSchemaId:
example: consch_JEL0WCBK
type: string
mode:
enum:
- create_and_fill
- fill
- update
type: string
type:
enum:
- inventory_plate_table
type: string
type: object
SimpleNotePart:
allOf:
- $ref: '#/components/schemas/BaseNotePart'
- properties:
links:
description: 'Array of links referenced in text via an @-mention, hyperlink, or the drag-n-dropped preview attached to the note.
'
items:
$ref: '#/components/schemas/EntryLink'
type: array
text:
description: The textual contents of the note.
type: string
type:
enum:
- text
- code
- list_bullet
- list_number
type: string
type: object
description: 'Simple note parts include the following types: - ''text'': plain text - ''code'': preformatted code block - ''list_bullet'': one "line" of a bulleted list - ''list_number'': one "line" of a numbered list
'
EntriesArchive:
additionalProperties: false
properties:
entryIds:
description: Array of entry IDs
items:
type: string
type: array
reason:
description: 'Reason that entries are being archived. One of ["Made in error", "Retired", "Other"].
'
enum:
- Made in error
- Retired
- Other
type: string
required:
- entryIds
- reason
type: object
ReviewChange:
additionalProperties: false
properties:
action:
description: The action which was performed with this change
enum:
- SEND_FOR_REVIEW
- ACCEPT
- REJECT
- COMMENT
- RETRACT
type: string
comment:
description: The comment which was left when the Review Change was submitted
nullable: true
type: string
createdAt:
description: DateTime the Review Change was created at
format: date-time
type: string
esigned:
description: Was the action verified through an e-signature compliant step
type: boolean
id:
type: string
reviewSnapshot:
allOf:
- $ref: '#/components/schemas/ReviewSnapshot'
description: Review Snapshot generated from this Review Change
nullable: true
type: object
Fields:
additionalProperties:
$ref: '#/components/schemas/Field'
type: object
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
StructuredTableApiIdentifiers:
properties:
apiId:
type: string
columns:
items:
$ref: '#/components/schemas/StructuredTableColumnInfo'
type: array
name:
type: string
type: object
EntryTableCell:
properties:
link:
allOf:
- $ref: '#/components/schemas/EntryLink'
description: '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:
description: 'The textual content of the cell. If the cell was originally a formula, this will be the evaluated version of the formula.
'
type: string
type: object
EntryTemplateUpdate:
additionalProperties: false
properties:
fields:
$ref: '#/components/schemas/Fields'
modifiedAt:
description: DateTime the template was last modified
type: string
name:
description: Title of the template
type: string
schemaId:
description: ID of the schema for the entry
type: string
templateCollectionId:
description: ID of the collection that contains the template
type: string
type: object
EntryNotePart:
description: 'Notes are the main building blocks of entries. Each note corresponds roughly to a paragraph.
'
discriminator:
mapping:
app_canvas: '#/components/schemas/AppCanvasNotePart'
assay_run: '#/components/schemas/AssayRunNotePart'
box_creation_table: '#/components/schemas/BoxCreationTableNotePart'
code: '#/components/schemas/SimpleNotePart'
external_file: '#/components/schemas/ExternalFileNotePart'
inventory_container_table: '#/components/schemas/InventoryContainerTableNotePart'
inventory_plate_table: '#/components/schemas/InventoryPlateTableNotePart'
list_bullet: '#/components/schemas/SimpleNotePart'
list_checkbox: '#/components/schemas/CheckboxNotePart'
list_number: '#/components/schemas/SimpleNotePart'
lookup_table: '#/components/schemas/LookupTableNotePart'
mixture_prep_table: '#/components/schemas/MixturePrepTableNotePart'
note_linked_chart: '#/components/schemas/ChartNotePart'
plate_creation_table: '#/components/schemas/PlateCreationTableNotePart'
registration_table: '#/components/schemas/RegistrationTableNotePart'
results_table: '#/components/schemas/ResultsTableNotePart'
table: '#/components/schemas/TableNotePart'
text: '#/components/schemas/SimpleNotePart'
text_box: '#/components/schemas/TextBoxNotePart'
propertyName: type
oneOf:
- $ref: '#/components/schemas/SimpleNotePart'
- $ref: '#/components/schemas/TableNotePart'
- $ref: '#/components/schemas/TextBoxNotePart'
- $ref: '#/components/schemas/CheckboxNotePart'
- $ref: '#/components/schemas/ExternalFileNotePart'
- $ref: '#/components/schemas/AssayRunNotePart'
- $ref: '#/components/schemas/LookupTableNotePart'
- $ref: '#/components/schemas/ResultsTableNotePart'
- $ref: '#/components/schemas/RegistrationTableNotePart'
- $ref: '#/components/schemas/PlateCreationTableNotePart'
- $ref: '#/components/schemas/BoxCreationTableNotePart'
- $ref: '#/components/schemas/MixturePrepTableNotePart'
- $ref: '#/components/schemas/InventoryContainerTableNotePart'
- $ref: '#/components/schemas/InventoryPlateTableNotePart'
- $ref: '#/components/schemas/ChartNotePart'
- $ref: '#/components/schemas/AppCanvasNotePart'
type: object
CustomField:
properties:
value:
type: string
type: object
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
BadRequestError:
properties:
error:
allOf:
- $ref: '#/components/schemas/BaseError'
- properties:
type:
enum:
- invalid_request_error
type: string
type: object
TextBoxNotePart:
allOf:
- $ref: '#/components/schemas/BaseNotePart'
- properties:
links:
description: 'Array of links referenced via an @-mention, hyperlink, or the drag-n-dropped preview attached to the note.
'
items:
$ref: '#/components/schemas/EntryLink'
type: array
name:
type: string
text:
type: string
type:
enum:
- text_box
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
# --- 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