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 Result API
version: 2.0.0
description: 'A Result represents a single row of experimental measurement data in Benchling''s lab
automation system. Results conform to a ResultSchema that defines their field structure,
enabling standardized capture of assay outputs such as absorbance readings, Ct values,
concentrations, or other measured quantities. Results are typically created through
lab automation output processors (see AutomationOutputProcessor), structured result
tables in notebook entries (via the entry field), or programmatically via the API.
Each result belongs to a Project for access control and can be archived when no longer
needed. Results can be linked to entities, samples, and runs through schema field values,
enabling traceability from raw measurements back to source materials.'
servers:
- url: /api/v3
security:
- oAuth: []
- basicApiKeyAuth: []
tags:
- description: 'A Result represents a single row of experimental measurement data in Benchling''s lab
automation system. Results conform to a ResultSchema that defines their field structure,
enabling standardized capture of assay outputs such as absorbance readings, Ct values,
concentrations, or other measured quantities. Results are typically created through
lab automation output processors (see AutomationOutputProcessor), structured result
tables in notebook entries (via the entry field), or programmatically via the API.
Each result belongs to a Project for access control and can be archived when no longer
needed. Results can be linked to entities, samples, and runs through schema field values,
enabling traceability from raw measurements back to source materials.'
name: Result
x-bnch-core-type: Result
x-bnch-organization: Benchling
paths:
/result:
post:
description: Create Result.
operationId: Result.Create
parameters:
- description: Set to true to access beta operations via /api/v3.
in: header
name: EARLY-ACCESS
required: false
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateResultInput'
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Result'
description: Created
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Create Result
tags:
- Result
x-bnch-rate-limit-tier: 4
/result/items:
get:
description: List Result items.
operationId: Result.List
parameters:
- $ref: '#/components/parameters/archiveReason.anyOf'
- $ref: '#/components/parameters/archived.anyOf'
- $ref: '#/components/parameters/createdAt.gt'
- $ref: '#/components/parameters/createdAt.gte'
- $ref: '#/components/parameters/createdAt.lt'
- $ref: '#/components/parameters/createdAt.lte'
- $ref: '#/components/parameters/creator.anyOf'
- $ref: '#/components/parameters/entry.anyOf'
- $ref: '#/components/parameters/entry.eq'
- $ref: '#/components/parameters/id.anyOf'
- $ref: '#/components/parameters/modifiedAt.gt'
- $ref: '#/components/parameters/modifiedAt.gte'
- $ref: '#/components/parameters/modifiedAt.lt'
- $ref: '#/components/parameters/modifiedAt.lte'
- $ref: '#/components/parameters/nextToken'
- $ref: '#/components/parameters/omit'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/project.eq'
- $ref: '#/components/parameters/returning'
- $ref: '#/components/parameters/schema.anyOf'
- $ref: '#/components/parameters/schema.eq'
- description: 'Method by which to order results. Valid sorts are: createdAt (created time, oldest first) and modifiedAt (modified time, oldest first). Use :asc or :desc to specify ascending or descending order. Default is modifiedAt:desc.'
in: query
name: sort
schema:
default: modifiedAt:desc
enum:
- createdAt:asc
- createdAt:desc
- modifiedAt:asc
- modifiedAt:desc
type: string
- description: Set to true to access beta operations via /api/v3.
in: header
name: EARLY-ACCESS
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ResultPaginatedList'
description: OK
headers: {}
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
summary: List Result items
tags:
- Result
x-bnch-rate-limit-tier: 4
/result/{result_id}:
get:
description: Get a single Result by ID.
operationId: Result.Get
parameters:
- description: ID of the Result.
in: path
name: result_id
required: true
schema:
type: string
- $ref: '#/components/parameters/returning'
- $ref: '#/components/parameters/omit'
- description: Set to true to access beta operations via /api/v3.
in: header
name: EARLY-ACCESS
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Result'
description: OK
headers: {}
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Get Result by ID
tags:
- Result
x-bnch-rate-limit-tier: 5
patch:
description: Update Result.
operationId: Result.Update
parameters:
- description: ID of the Result.
in: path
name: result_id
required: true
schema:
type: string
- description: Set to true to access beta operations via /api/v3.
in: header
name: EARLY-ACCESS
required: false
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateResultInput'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Result'
description: OK
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Update Result
tags:
- Result
x-bnch-rate-limit-tier: 4
/result:batch-create:
post:
description: Batch create Result synchronously in one transaction. Maximum 25 items per request.
operationId: Result.BatchCreate
parameters:
- description: Set to true to access beta operations via /api/v3.
in: header
name: EARLY-ACCESS
required: false
schema:
type: string
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties:
items:
items:
$ref: '#/components/schemas/CreateResultInput'
maxItems: 25
minItems: 1
type: array
required:
- items
type: object
responses:
'201':
content:
application/json:
schema:
additionalProperties: false
properties:
items:
items:
$ref: '#/components/schemas/Result'
type: array
required:
- items
type: object
description: Created
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Batch create Result
tags:
- Result
x-bnch-rate-limit-tier: 3
/result:batch-update:
patch:
description: Batch update Result synchronously in one transaction. Maximum 25 items per request.
operationId: Result.BatchUpdate
parameters:
- description: Set to true to access beta operations via /api/v3.
in: header
name: EARLY-ACCESS
required: false
schema:
type: string
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties:
items:
items:
$ref: '#/components/schemas/UpdateResultInputWithPathParams'
maxItems: 25
minItems: 1
type: array
required:
- items
type: object
responses:
'200':
content:
application/json:
schema:
additionalProperties: false
properties:
items:
items:
$ref: '#/components/schemas/Result'
type: array
required:
- items
type: object
description: OK
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Batch update Result
tags:
- Result
x-bnch-rate-limit-tier: 3
/result:bulk-create:
post:
description: Bulk create Result.
operationId: Result.BulkCreate
parameters:
- description: Set to true to access beta operations via /api/v3.
in: header
name: EARLY-ACCESS
required: false
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BulkImport'
responses:
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncTaskLink'
description: Task started
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Bulk create Result
tags:
- Result
x-bnch-rate-limit-tier: 2
/result:bulk-update:
patch:
description: Bulk update Result.
operationId: Result.BulkUpdate
parameters:
- description: Set to true to access beta operations via /api/v3.
in: header
name: EARLY-ACCESS
required: false
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BulkImport'
responses:
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncTaskLink'
description: Task started
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Bulk update Result
tags:
- Result
x-bnch-rate-limit-tier: 2
components:
schemas:
FieldValueInput:
additionalProperties: false
properties:
value:
$ref: '#/components/schemas/AnyType'
required:
- value
type: object
AnyType: {}
UpdateResultInput:
additionalProperties: false
properties:
archiveReason:
type: string
archived:
type: boolean
schemaFields:
additionalProperties:
$ref: '#/components/schemas/FieldValueInput'
type: object
type: object
DateValue:
description: A type that represents date values.
properties:
__typename:
type: string
value:
description: The date value.
format: date
type: string
type: object
Result:
allOf:
- $ref: '#/components/schemas/IResult'
- description: 'A Result represents a single row of experimental measurement data in Benchling''s lab
automation system. Results conform to a ResultSchema that defines their field structure,
enabling standardized capture of assay outputs such as absorbance readings, Ct values,
concentrations, or other measured quantities. Results are typically created through
lab automation output processors (see AutomationOutputProcessor), structured result
tables in notebook entries (via the entry field), or programmatically via the API.
Each result belongs to a Project for access control and can be archived when no longer
needed. Results can be linked to entities, samples, and runs through schema field values,
enabling traceability from raw measurements back to source materials.'
properties:
__typename:
type: string
creator:
description: User who created the request
oneOf:
- $ref: '#/components/schemas/PrincipalRef'
- type: 'null'
entry:
description: Entry that this result is attached to
oneOf:
- $ref: '#/components/schemas/DocumentLikeRef'
- type: 'null'
schemaFields:
oneOf:
- items:
$ref: '#/components/schemas/SchemaFieldValue'
type: array
- type: 'null'
type: object
BooleanValue:
description: A type that represents boolean values.
properties:
__typename:
type: string
value:
description: The boolean value.
type: boolean
type: object
ProjectRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
type: object
ObjectLinkValue:
description: A type that represents links to other objects.
properties:
__typename:
type: string
value:
$ref: '#/components/schemas/ObjectRef'
description: The object that this value links to, or an Inaccessible object if not found with the current permission set.
type: object
CreateResultInput:
additionalProperties: false
properties:
projectId:
type: string
schemaFields:
additionalProperties:
$ref: '#/components/schemas/FieldValueInput'
type: object
schemaId:
type: string
tableHandleId:
type: string
required:
- schemaId
- schemaFields
- projectId
type: object
SchemaFieldValue:
description: 'Represents a field value on a schematized object, pairing a `fieldDefinition` (describing the
field''s type and constraints) with its actual `value` (a `BenchlingValue` such as text, number,
date, or link to another object). The value may be null if no value has been set. Used within
the `schemaFields` collection on objects that implement `HasSchema` to provide access to all
custom field values defined by the object''s schema.'
properties:
__typename:
type: string
fieldDefinition:
$ref: '#/components/schemas/SchemaFieldDefinitionRef'
id:
type: string
linkedEntityId:
type:
- 'null'
- string
value:
description: Union of BooleanValue, DateTimeValue, DateValue, DecimalValue, IntegerValue, JsonValue, ObjectLinkValue, ObjectLinkListValue, TextAndUrlValue, TextValue, ArrayValue
oneOf:
- anyOf:
- $ref: '#/components/schemas/BooleanValue'
- $ref: '#/components/schemas/DateTimeValue'
- $ref: '#/components/schemas/DateValue'
- $ref: '#/components/schemas/DecimalValue'
- $ref: '#/components/schemas/IntegerValue'
- $ref: '#/components/schemas/JsonValue'
- $ref: '#/components/schemas/ObjectLinkValue'
- $ref: '#/components/schemas/ObjectLinkListValue'
- $ref: '#/components/schemas/TextAndUrlValue'
- $ref: '#/components/schemas/TextValue'
- $ref: '#/components/schemas/ArrayValue'
discriminator:
propertyName: __typename
- type: 'null'
type: object
InternalServerError:
properties:
detail:
type:
- 'null'
- string
- object
errorId:
type: string
instance:
type: string
status:
type: integer
title:
type:
- 'null'
- string
type:
type: string
required:
- type
- title
- detail
- status
- instance
type: object
DecimalValue:
description: A type that represents decimal value as strings.
properties:
__typename:
type: string
numericValue:
deprecated: true
description: Deprecated. The float representation of the decimal value.
type:
- 'null'
- number
value:
description: The decimal value in a string representation
type:
- 'null'
- string
type: object
UpdateResultInputWithPathParams:
additionalProperties: false
properties:
archiveReason:
type: string
archived:
type: boolean
id:
type: string
schemaFields:
additionalProperties:
$ref: '#/components/schemas/FieldValueInput'
type: object
required:
- id
type: object
ResultSchemaRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
type: object
ArrayValue:
description: A type that represents a list of BenchlingValues, used for multi-value cells (e.g. alias columns).
properties:
__typename:
type: string
value:
items:
anyOf:
- $ref: '#/components/schemas/BooleanValue'
- $ref: '#/components/schemas/DateTimeValue'
- $ref: '#/components/schemas/DateValue'
- $ref: '#/components/schemas/DecimalValue'
- $ref: '#/components/schemas/IntegerValue'
- $ref: '#/components/schemas/JsonValue'
- $ref: '#/components/schemas/ObjectLinkValue'
- $ref: '#/components/schemas/ObjectLinkListValue'
- $ref: '#/components/schemas/TextAndUrlValue'
- $ref: '#/components/schemas/TextValue'
description: Union of BooleanValue, DateTimeValue, DateValue, DecimalValue, IntegerValue, JsonValue, ObjectLinkValue, ObjectLinkListValue, TextAndUrlValue, TextValue
discriminator:
propertyName: __typename
type: array
type: object
AsyncTaskLink:
properties:
pollingUri:
format: uri
type: string
taskId:
type: string
type: object
BulkImport:
example:
fileId: scrfile_jdf8BV24kLmN
properties:
fileId:
description: The API ID of the scratch file (`scrfile_XXXXXXXX`) containing the items to import. The referenced file must be a scratch file whose upload has completed successfully.
type: string
required:
- fileId
type: object
ResultPaginatedList:
additionalProperties: false
properties:
items:
items:
$ref: '#/components/schemas/Result'
type: array
nextToken:
type: string
type: object
PrincipalRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
type: object
DocumentLikeRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
type: object
DateTimeValue:
description: A type that represents datetime values.
properties:
__typename:
type: string
value:
description: The datetime value with UTC as the timezone.
format: datetime
type: string
type: object
ObjectRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
type: object
TextValue:
description: A type that represents text (string) values.
properties:
__typename:
type: string
value:
description: The text value. It may or may not be an empty string.
type: string
type: object
JsonValue:
description: A type that represents JSON values.
properties:
__typename:
type: string
value:
description: The JSON value.
type: object
type: object
TextAndUrlValue:
description: A type that represents text (string) values with an associated URL.
properties:
__typename:
type: string
url:
description: The URL associated with the value. Please use `TextValue` if you don't want a URL.
type: string
value:
description: The text value. It may or may not be an empty string.
type: string
type: object
IntegerValue:
description: A type that represents integer values.
properties:
__typename:
type: string
value:
description: The integer value.
type: integer
type: object
SchemaFieldDefinitionRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
type: object
ObjectLinkListValue:
description: A type that represents a list of links to other objects.
properties:
__typename:
type: string
value:
description: The list of objects that this value links to. Inaccessible objects may be returned instead if the object is not found with the current permission set.
items:
$ref: '#/components/schemas/ObjectRef'
description: Union of AaSequence, Box, Container, CustomEntity, DnaSequence, DropdownOption, Entry, Location, Mixture, Molecule, Plate, Result, RnaSequence, Run, DnaOligo, RnaOligo
type: array
type: object
GeneralError:
properties:
detail:
type:
- 'null'
- string
- object
instance:
type: string
status:
type: integer
title:
type:
- 'null'
- string
type:
type: string
required:
- type
- title
- detail
- status
- instance
type: object
IResult:
properties:
__typename:
type: string
archiveReason:
type:
- 'null'
- string
archived:
type: boolean
createdAt:
description: DateTime at which the the result was created
format: datetime
type:
- 'null'
- string
id:
description: ID of the result
type: string
modifiedAt:
description: DateTime at which the the result was last modified
format: datetime
type:
- 'null'
- string
project:
description: The project that the result is in
oneOf:
- $ref: '#/components/schemas/ProjectRef'
- type: 'null'
schema:
description: Schema that the result belongs to
oneOf:
- $ref: '#/components/schemas/ResultSchemaRef'
- type: 'null'
type: object
parameters:
pageSize:
description: Number of results to return. Defaults to 50, maximum of 100.
in: query
name: pageSize
schema:
type: integer
createdAt.gte:
description: Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those created at or after the specified time. e.g. >= 2017-04-30.
in: query
name: createdAt.gte
schema:
format: datetime
type: string
modifiedAt.gt:
description: Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those modified after the specified time. e.g. > 2017-04-30.
in: query
name: modifiedAt.gt
schema:
format: datetime
type: string
modifiedAt.lte:
description: Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those modified at or before the specified time. e.g. <= 2017-04-30.
in: query
name: modifiedAt.lte
schema:
format: datetime
type: string
id.anyOf:
description: Restricts results to those matching any of the specified IDs. Comma-separated list.
explode: false
in: query
name: id.anyOf
schema:
items:
type: string
maxItems: 100
type: array
omit:
description: Comma-separated list of top-level fields to omit from each returned item. Cannot overlap with returning.
explode: false
in: query
name: omit
schema:
items:
type: string
type: array
modifiedAt.lt:
description: Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those modified before the specified time. e.g. < 2017-04-30.
in: query
name: modifiedAt.lt
schema:
format: datetime
type: string
project.eq:
description: ID of a project. Restricts results to those in the project.
in: query
name: project.eq
schema:
type: string
creator.anyOf:
description: Restricts results to those created by any of the specified user IDs. Comma-separated list.
explode: false
in: query
name: creator.anyOf
schema:
items:
type: string
maxItems: 100
type: array
entry.eq:
description: Single entry ID. Restricts results to those in the specified entry.
in: query
name: entry.eq
schema:
type: string
createdAt.gt:
description: Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those created after the specified time. e.g. > 2017-04-30.
in: query
name: createdAt.gt
schema:
format: datetime
type: string
schema.anyOf:
description: Restricts results to those that match any of the specified schema IDs. Use only one `schema` filter arg at a time. Comma-separated list.
explode: false
in: query
name: schema.anyOf
schema:
items:
type: string
maxItems: 100
type: array
createdAt.lt:
description: Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those created before the specified time. e.g. < 2017-04-30.
in: query
name: createdAt.lt
schema:
format: datetime
type: string
archiveReason.anyOf:
description: Restricts items to those with any of the specified archive reasons. Use "NOT_ARCHIVED" to filter for unarchived items. Use "ANY_ARCHIVED" to filter for archived items regardless of reason. Use "ANY_ARCHIVED_OR_NOT_ARCHIVED" to return items for both archived and unarchived. Comma-separated list.
explode: false
in: query
name: archiveReason.anyOf
schema:
items:
type: string
maxItems: 10
type: array
returning:
description: Comma-separated list of top-level fields to include in each returned item. Cannot overlap with omit.
explode: false
in: query
name: returning
schema:
items:
type: string
type: array
archived.anyOf:
description: If true, returns archived items. If false, returns unarchived items. If both true and false, returns archived and unarchived items. Comma-separated list.
explode: false
in: query
name: archived.anyOf
schema:
items:
type: boolean
maxItems: 2
type: array
nextToken:
description: Token for pagination
in: query
name: nextToken
schema:
type: string
entry.anyOf:
description: Restricts results to those in entries matching any of the specified entry IDs. Comma-separated list.
explode: false
in: query
name: entry.anyOf
schema:
items:
type: string
maxItems: 100
type: array
modifiedAt.gte:
description: Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those modified at or after the specified time. e.g. >= 2017-04-30.
in: query
name: modifiedAt.gte
schema:
format: datetime
type: string
schema.eq:
description: Single schema ID. Restricts results to those that match the specified schema exactly. Use only one `schema` filter arg at a time.
in: query
name: schema.eq
schema:
type: string
createdAt.lte:
description: Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those created at or before the specified time. e.g. <= 2017-04-30.
in: query
name: createdAt.lte
schema:
format: datetime
type: string
responses:
NotFound:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/GeneralError'
description: Not Found
TooManyRequests:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/GeneralError'
description: Too Many Requests
BadRequest:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/GeneralError'
description: Bad Request
Forbidden:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/GeneralError'
description: Forbidden
InternalServerError:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/InternalServerError'
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/benchling/refs/heads/main/openapi/benchling-result-api-openapi.yml