BEbenchling
search

Search across Benchling objects

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. Search supports stable and beta object types. The returned source object can include stable and beta fields.

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.

post/api/v3/search

Request

  • Base URL
    https://{tenant_name}.benchling.com
  • Auth
    HTTP bearer

Headers

EARLY-ACCESSstring

Set to true to access beta operations via /api/v3.

Request body

nextTokenstring

Opaque pagination token returned by the previous response. Use it with otherwise identical request parameters.

objectTypesSearchPostRequestBodyContentApplicationJsonSchemaObjectTypesItems[]

Restrict results to one or more object types, using PascalCase names. The object types listed for this field are supported by the endpoint, but some may not be available to your Benchling tenant. If omitted or empty, the search includes every available object type compatible with all provided filters. A schemaFields filter restricts the search to the object type associated with the fields' schema. The request is rejected with a 400 if no searchable type supports the complete filter combination. When a non-empty list is provided, every requested type must be compatible with every provided filter; otherwise the request is rejected with a 400. When schemaFields is provided, only the object type associated with the fields' schema can be requested. If objectTypes includes a supported type that is not available to your Benchling tenant, the request is rejected with a 400. Whether explicitly provided or automatically determined, the set of types that were searched is returned in the searchedObjectTypes field of the response.

omitstring[]

Top-level fields to omit from each hit's source. Use the same public field names as V3 Get/List responses. Cannot overlap with returning. Because search results can span multiple object types, a field is accepted if it exists on at least one searched type. Omitting a field that does not exist on a given hit's type has no effect on that hit.

pageSizeinteger

Number of results per page. Defaults to 50, max 100.

querystring

Free-text query matched against indexed object names, schema and custom field values, and searchable textual content. Extracted attachment text is included where supported and available. Searchable content varies by object type, and not every field returned in source is searchable. All whitespace-separated terms must match. Enclose multiple words in double quotes to search for them as a phrase. Boolean operators, wildcards, and field-qualified terms are not supported. If omitted, returns all accessible items matching the provided filters.

returningstring[]

Top-level fields to include in each hit's source. Use the same public field names as V3 Get/List responses. Cannot overlap with omit. Because search results can span multiple object types, a field is accepted if it exists on at least one searched type. Each hit only includes the selected fields that exist on its own type; selected fields that belong only to other searched types are absent from that hit's source. id and __typename are always included, matching V3 List/Get.

sort'barcode:asc' | 'barcode:desc' | 'createdAt:asc' | 'createdAt:desc' | 'modifiedAt:asc' | 'modifiedAt:desc' | 'name:asc' | 'name:desc'

Sort order for results, in field:direction format (same as V3 List endpoint sort params). When omitted, defaults to most-relevant-first if query is non-empty, otherwise modifiedAt:desc (unless a score-based filter such as chemicalStructure is applied; see filter descriptions). Providing sort overrides relevance or filter score ordering. Results missing the sort field sort last in both directions (for example, a notebook entry when sorting by barcode).

Response

OK

nextTokenstring nullable required

Opaque cursor for fetching the next page. Null when there are no more results.

Changes

No recorded changes to this operation across all 1 revision of this API.