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 Search API
version: 2.0.0
servers:
- url: /api/v3
security:
- oAuth: []
- basicApiKeyAuth: []
tags:
- name: Search
paths:
/search:
post:
description: 'Search across Benchling objects that the caller has permission to view. Results can span multiple object types, and each hit includes the object''s V3 representation in `source`.
## Consistency
Search result matching is eventually consistent: queries and filters are evaluated against an asynchronously updated search index, so recent changes may not immediately affect which objects match.
After identifying matches from the index, the endpoint loads their current V3 representations into `source`. This provides up-to-date object details, although recently changed fields may differ from the indexed values used for matching. Objects that have since been deleted or become inaccessible because of permission changes are omitted.'
operationId: Search.Search.SyncCustom
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:
examples:
global_free_text_search:
summary: Global text search, sorted by relevance
value:
query: expression plasmid
schema_field_search:
summary: Filter by schema-defined fields
value:
filters:
schemaFields:
tsf_abc123:
eq: Active
tsf_def456:
gte: 10
lt: 20
objectTypes:
- CustomEntity
targeted_search:
summary: Scoped search with filters
value:
filters:
createdAt:
gte: '2026-01-01T00:00:00Z'
creator:
anyOf:
- usr_abc123
objectTypes:
- Entry
- DnaSequence
- Protein
pageSize: 20
query: expression plasmid
sort: modifiedAt:desc
schema:
additionalProperties: false
properties:
filters:
additionalProperties: false
description: 'Structured filters applied to narrow the matching result set. Field names match the query parameters on per-entity List endpoints, and each field maps to an object of operators. Each standard filter key''s description lists the objectTypes that support it.
The special `schemaFields` key filters by schema-defined field values, see the field''s description for more information.
All filters are implicitly ANDed together. Archived objects are excluded unless an `archived` filter is provided.'
example:
createdAt:
gte: '2025-09-15T05:22:30Z'
schemaFields:
tsf_abc123:
eq: PD-L1
properties:
aminoAcids:
additionalProperties: false
description: 'Supported objectTypes: AaSequence.'
minProperties: 1
properties:
anyOf:
description: Restricts results to those whose sequence exactly matches any of the specified amino acid sequences (case-insensitive).
items:
type: string
maxItems: 100
type: array
type: object
archived:
additionalProperties: false
description: 'Supported objectTypes: AaSequence, Analysis, AnalysisTemplate, Assembly, Box, Container, CustomEntity, DnaOligo, DnaSequence, Entry, File, Folder, Location, MatrixPlate, OligoConjugate, OligoDuplex, PlateDesignTemplate, Procedure, Protein, RequestV2Definition, RequestV2Submission, RnaOligo, RnaSequence, Study, TestDefinition, WellPlate, WorkflowTaskGroup, Worksheet.'
minProperties: 1
properties:
anyOf:
description: If true, returns archived items. If false, returns unarchived items. If both true and false, returns archived and unarchived items.
items:
type: boolean
maxItems: 2
type: array
type: object
authors:
additionalProperties: false
description: 'Supported objectTypes: AaSequence, CustomEntity, DnaOligo, DnaSequence, Entry, Protein, RnaOligo, RnaSequence.'
minProperties: 1
properties:
anyOf:
description: Restricts results to those whose author matches any of the specified user or author IDs.
items:
type: string
maxItems: 100
type: array
type: object
barcode:
additionalProperties: false
description: 'Supported objectTypes: Box, Container, Location, MatrixPlate, WellPlate.'
minProperties: 1
properties:
anyOf:
description: Restricts results to those matching any of the specified barcodes. Fails and reports any invalid barcodes.
items:
type: string
maxItems: 100
type: array
type: object
bases:
additionalProperties: false
description: 'Supported objectTypes: DnaSequence, RnaSequence.'
minProperties: 1
properties:
anyOf:
description: Restricts results to those whose sequence exactly matches any of the specified DNA base sequences (case-insensitive, accounting for circular and reverse complement).
items:
type: string
maxItems: 100
type: array
type: object
createdAt:
additionalProperties: false
description: 'Supported objectTypes: AaSequence, Analysis, AnalysisTemplate, AppSession, Assembly, Box, Container, CustomEntity, DnaOligo, DnaSequence, Entry, FeatureLibrary, File, Location, MatrixPlate, NucleotideAlignment, OligoConjugate, OligoDuplex, PlateDesignTemplate, Procedure, Protein, RequestV2Definition, RequestV2Submission, RnaOligo, RnaSequence, Study, Team, TestDefinition, WellPlate, WorkflowTaskGroup, Worklist, Worksheet.'
minProperties: 1
properties:
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.
format: datetime
type: string
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.
format: datetime
type: string
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.
format: datetime
type: string
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.
format: datetime
type: string
type: object
creator:
additionalProperties: false
description: 'Supported objectTypes: AaSequence, AnalysisTemplate, Box, Container, CustomEntity, DnaOligo, DnaSequence, Entry, Location, MatrixPlate, OligoConjugate, OligoDuplex, Procedure, Protein, RnaOligo, RnaSequence, TestDefinition, WellPlate, Worksheet.'
minProperties: 1
properties:
anyOf:
description: Restricts results to those created by any of the specified user IDs.
items:
type: string
maxItems: 100
type: array
type: object
fieldset:
additionalProperties: false
description: 'Supported objectTypes: AaSequence, CustomEntity, DnaOligo, DnaSequence, Protein, RnaOligo, RnaSequence.'
minProperties: 1
properties:
anyOf:
description: Restricts results to those whose schema implements any of the specified fieldset API IDs (custom schema interfaces).
items:
type: string
maxItems: 100
type: array
type: object
id:
additionalProperties: false
description: 'Supported objectTypes: AaSequence, Analysis, AnalysisTemplate, AppSession, Assembly, Box, Container, CustomEntity, DnaOligo, DnaSequence, Entry, FeatureLibrary, File, Folder, Location, MatrixPlate, NucleotideAlignment, OligoConjugate, OligoDuplex, PlateDesignTemplate, Procedure, Protein, RequestV2Definition, RequestV2Submission, RnaOligo, RnaSequence, Study, Team, TestDefinition, User, WellPlate, WorkflowTaskGroup, Worklist, Worksheet.'
minProperties: 1
properties:
anyOf:
description: Restricts results to those matching any of the specified IDs.
items:
type: string
maxItems: 100
type: array
type: object
mentionedIn:
additionalProperties: false
description: 'Supported objectTypes: AaSequence, Box, Container, CustomEntity, DnaOligo, DnaSequence, Entry, Location, Protein, RnaOligo, RnaSequence.'
minProperties: 1
properties:
anyOf:
description: Restricts results to items mentioned in entries matching any of the specified entry IDs.
items:
type: string
maxItems: 100
type: array
type: object
modifiedAt:
additionalProperties: false
description: 'Supported objectTypes: AaSequence, Analysis, AnalysisTemplate, AppSession, Assembly, Box, Container, CustomEntity, DnaOligo, DnaSequence, Entry, FeatureLibrary, File, Folder, Location, MatrixPlate, NucleotideAlignment, OligoConjugate, OligoDuplex, PlateDesignTemplate, Procedure, Protein, RequestV2Definition, RequestV2Submission, RnaOligo, RnaSequence, Study, Team, TestDefinition, User, WellPlate, WorkflowTaskGroup, Worklist, Worksheet.'
minProperties: 1
properties:
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.
format: datetime
type: string
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.
format: datetime
type: string
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.
format: datetime
type: string
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.
format: datetime
type: string
type: object
name:
additionalProperties: false
description: 'Supported objectTypes: AaSequence, Analysis, AnalysisTemplate, Assembly, Box, Container, CustomEntity, DnaOligo, DnaSequence, Entry, File, Folder, Location, MatrixPlate, NucleotideAlignment, OligoConjugate, OligoDuplex, Procedure, Protein, RequestV2Definition, RequestV2Submission, RnaOligo, RnaSequence, Study, Team, TestDefinition, User, WellPlate, Worklist, Worksheet.'
minProperties: 1
properties:
anyOf:
description: Restricts results to those that match any of the specified names. Case insensitive. Warning - this filter can be non-performant due to case insensitivity. Ensure only one name filter is used at a time.
items:
type: string
maxItems: 100
type: array
caseSensitive:
default: false
description: Restricts results to those that match any of the specified names. Case sensitive. Ensure only one name filter is used at a time.
type: boolean
type: object
parent:
additionalProperties: false
description: 'Supported objectTypes: Folder.'
minProperties: 1
properties:
eq:
description: ID of a folder. Restricts results to its direct children.
type: string
type: object
parentStorage:
additionalProperties: false
description: 'Supported objectTypes: Box, Container, Location, MatrixPlate, WellPlate.'
minProperties: 1
properties:
eq:
description: ID of a location. Restricts results to those located in the specified inventory.
type: string
type: object
project:
additionalProperties: false
description: 'Supported objectTypes: AaSequence, CustomEntity, DnaOligo, DnaSequence, Folder, OligoConjugate, OligoDuplex, Protein, RnaOligo, RnaSequence.'
minProperties: 1
properties:
eq:
description: ID of a project. Restricts results to those in the project.
type: string
type: object
registry:
additionalProperties: false
description: 'Supported objectTypes: AaSequence, CustomEntity, DnaOligo, DnaSequence, Protein, RnaOligo, RnaSequence.'
minProperties: 1
properties:
eq:
description: ID of a registry. Restricts results to those registered in this registry. Specifying "null" returns unregistered items.
type: string
type: object
schema:
additionalProperties: false
description: 'Supported objectTypes: AaSequence, Box, CustomEntity, DnaOligo, DnaSequence, Entry, Location, Protein, RnaOligo, RnaSequence.'
minProperties: 1
properties:
anyOf:
description: Restricts results to those that match any of the specified schema IDs. Use only one `schema` filter arg at a time.
items:
type: string
maxItems: 100
type: array
eq:
description: Single schema ID. Restricts results to those that match the specified schema exactly. Use only one `schema` filter arg at a time.
type: string
type: object
schemaFields:
additionalProperties:
anyOf:
- additionalProperties: true
description: Operators supported by text and long text schema fields. Matching is case-insensitive.
example:
eq: PD-L1
minProperties: 1
properties:
anyOf:
description: Match any of the specified values.
oneOf:
- type: string
- items:
type: string
minItems: 1
type: array
eq:
description: Match the value exactly.
type: string
excludes:
description: Exclude values containing any of the specified text.
oneOf:
- type: string
- items:
type: string
minItems: 1
type: array
includes:
description: Match values containing any of the specified text.
oneOf:
- type: string
- items:
type: string
minItems: 1
type: array
isEmpty:
const: true
description: Match fields with no value. The operand must be `true`.
type: boolean
isNotEmpty:
const: true
description: Match fields with a value. The operand must be `true`.
type: boolean
noneOf:
description: Exclude all of the specified values.
oneOf:
- type: string
- items:
type: string
minItems: 1
type: array
not:
description: Exclude an exact value.
type: string
startsWith:
description: Match values beginning with any of the specified text.
oneOf:
- type: string
- items:
type: string
minItems: 1
type: array
title: Text or long text field
type: object
- additionalProperties: true
description: Operators supported by integer schema fields.
example:
gte: 1
lt: 10
minProperties: 1
properties:
anyOf:
description: Match any of the specified values.
items:
type: integer
minItems: 1
type: array
eq:
description: Match the specified value.
type: integer
gt:
description: Match values greater than the operand.
type: integer
gte:
description: Match values greater than or equal to the operand.
type: integer
isEmpty:
const: true
description: Match fields with no value. The operand must be `true`.
type: boolean
isNotEmpty:
const: true
description: Match fields with a value. The operand must be `true`.
type: boolean
lt:
description: Match values less than the operand.
type: integer
lte:
description: Match values less than or equal to the operand.
type: integer
noneOf:
description: Exclude all of the specified values.
items:
type: integer
minItems: 1
type: array
title: Integer field
type: object
- additionalProperties: true
description: Operators supported by decimal schema fields. Numeric strings are accepted to preserve decimal precision.
example:
gte: 0.1
lt: 1.0
minProperties: 1
properties:
anyOf:
description: Match any of the specified values.
items:
oneOf:
- type: number
- type: string
minItems: 1
type: array
eq:
description: Match the specified value.
oneOf:
- type: number
- type: string
gt:
description: Match values greater than the operand.
oneOf:
- type: number
- type: string
gte:
description: Match values greater than or equal to the operand.
oneOf:
- type: number
- type: string
isEmpty:
const: true
description: Match fields with no value. The operand must be `true`.
type: boolean
isNotEmpty:
const: true
description: Match fields with a value. The operand must be `true`.
type: boolean
lt:
description: Match values less than the operand.
oneOf:
- type: number
- type: string
lte:
description: Match values less than or equal to the operand.
oneOf:
- type: number
- type: string
noneOf:
description: Exclude all of the specified values.
items:
oneOf:
- type: number
- type: string
minItems: 1
type: array
title: Decimal field
type: object
- additionalProperties: true
description: Operators supported by date schema fields. Dates use RFC 3339 full-date format (`YYYY-MM-DD`).
example:
gte: '2026-01-01'
lt: '2026-02-01'
minProperties: 1
properties:
anyOf:
description: Match any of the specified dates.
items:
format: date
type: string
minItems: 1
type: array
eq:
description: Match the specified date.
format: date
type: string
gt:
description: Match dates after the operand.
format: date
type: string
gte:
description: Match dates on or after the operand.
format: date
type: string
isEmpty:
const: true
description: Match fields with no value. The operand must be `true`.
type: boolean
isNotEmpty:
const: true
description: Match fields with a value. The operand must be `true`.
type: boolean
lt:
description: Match dates before the operand.
format: date
type: string
lte:
description: Match dates on or before the operand.
format: date
type: string
noneOf:
description: Exclude all of the specified dates.
items:
format: date
type: string
minItems: 1
type: array
title: Date field
type: object
- additionalProperties: true
description: Operators supported by datetime schema fields. Datetimes use RFC 3339 format; a datetime without an offset is interpreted as UTC.
example:
gte: '2026-01-01T00:00:00Z'
minProperties: 1
properties:
anyOf:
description: Match any of the specified datetimes.
items:
format: date-time
type: string
minItems: 1
type: array
eq:
description: Match the specified datetime.
format: date-time
type: string
gt:
description: Match datetimes after the operand.
format: date-time
type: string
gte:
description: Match datetimes on or after the operand.
format: date-time
type: string
isEmpty:
const: true
description: Match fields with no value. The operand must be `true`.
type: boolean
isNotEmpty:
const: true
description: Match fields with a value. The operand must be `true`.
type: boolean
lt:
description: Match datetimes before the operand.
format: date-time
type: string
lte:
description: Match datetimes on or before the operand.
format: date-time
type: string
noneOf:
description: Exclude all of the specified datetimes.
items:
format: date-time
type: string
minItems: 1
type: array
title: Datetime field
type: object
- additionalProperties: true
description: Operators supported by boolean schema fields.
example:
eq: true
minProperties: 1
properties:
eq:
description: Match fields equal to the operand.
type: boolean
isEmpty:
const: true
description: Match fields with no value. The operand must be `true`.
type: boolean
isNotEmpty:
const: true
description: Match fields with a value. The operand must be `true`.
type: boolean
title: Boolean field
type: object
- additionalProperties: true
description: Operators supported by link and dropdown schema fields. Operands are API IDs of linked objects or dropdown options.
example:
anyOf:
- bfi_abc123
- bfi_def456
minProperties: 1
properties:
allOf:
# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/benchling/refs/heads/main/openapi/benchling-search-api-openapi.yml