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 Template Collection API
version: 2.0.0
description: 'A container that organizes related templates, subtemplates, and other template-like
items. Template Collections provide a way to group and manage reusable content that
teams use to create standardized entries. Each collection has an owner (typically an
Organization or Team) and can be shared with others through access controls (see
`Collaboration`). Collections can contain `EntryTemplate`s for creating new entries,
`EntrySubtemplate`s for inserting content, form definitions, procedures, and analysis
templates. In the Benchling UI, these appear in the "Template Collections" section.'
servers:
- url: /api/v3
security:
- oAuth: []
- basicApiKeyAuth: []
tags:
- description: 'A container that organizes related templates, subtemplates, and other template-like
items. Template Collections provide a way to group and manage reusable content that
teams use to create standardized entries. Each collection has an owner (typically an
Organization or Team) and can be shared with others through access controls (see
`Collaboration`). Collections can contain `EntryTemplate`s for creating new entries,
`EntrySubtemplate`s for inserting content, form definitions, procedures, and analysis
templates. In the Benchling UI, these appear in the "Template Collections" section.'
name: TemplateCollection
x-bnch-organization: Benchling
paths:
/template-collection/items:
get:
description: List TemplateCollection items.
operationId: TemplateCollection.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/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/name.anyOf'
- $ref: '#/components/parameters/name.anyOf.caseSensitive'
- $ref: '#/components/parameters/nextToken'
- $ref: '#/components/parameters/omit'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/returning'
- 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/TemplateCollectionPaginatedList'
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 TemplateCollection items
tags:
- TemplateCollection
x-bnch-rate-limit-tier: 4
/template-collection/{template_collection_id}:
get:
description: Get a single TemplateCollection by ID.
operationId: TemplateCollection.Get
parameters:
- description: ID of the TemplateCollection.
in: path
name: template_collection_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/TemplateCollection'
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 TemplateCollection by ID
tags:
- TemplateCollection
x-bnch-rate-limit-tier: 5
/template-collection/{template_collection_id}/items/items:
get:
description: List TemplateCollectible items.
operationId: TemplateCollection.items.List
parameters:
- description: ID of the TemplateCollection.
in: path
name: template_collection_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
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TemplateCollectibleUnpaginatedList'
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 TemplateCollectible items
tags:
- TemplateCollection
x-bnch-rate-limit-tier: 4
components:
schemas:
ProcedureFlowchartRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
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
ScratchPlateRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
type: object
BooleanValue:
description: A type that represents boolean values.
properties:
__typename:
type: string
value:
description: The boolean value.
type: boolean
type: object
EntrySubtemplate:
description: 'A reusable content block that can be inserted into `DocumentLike` objects.
Subtemplates contain pre-defined note content (text, tables, etc.) that scientists
commonly need to repeat across multiple entries. Unlike `EntryTemplates` which create
entire new entries, subtemplates are inserted as sections within existing documents.
Subtemplates belong to a `TemplateCollection` and support versioned publishing (see
`PublishingRecord`) to ensure consistent use across the organization. In the UI,
these may be referred to simply as "Subtemplates" or "Insertable Content."'
properties:
__typename:
type: string
archiveReason:
type:
- 'null'
- string
archived:
type: boolean
createdAt:
description: DateTime the subtemplate was created at
format: datetime
type:
- 'null'
- string
creator:
description: User that created the subtemplate
oneOf:
- $ref: '#/components/schemas/PrincipalRef'
- type: 'null'
id:
description: ID of the subtemplate
type: string
modifiedAt:
description: DateTime the subtemplate was last modified
format: datetime
type:
- 'null'
- string
name:
description: Title of the subtemplate
type:
- 'null'
- string
templateCollection:
$ref: '#/components/schemas/TemplateCollectionRef'
description: Template collection that contains the template collectible
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
OwnerRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
type: object
CustomField:
description: 'A name-value pair for storing additional metadata on objects that support custom fields.
CustomFields provide a flexible way to attach arbitrary string data to entities, containers,
datasets, and other Benchling objects without modifying their schemas. Objects that can
have custom fields implement the HasCustomFields interface. Unlike schema-defined fields,
custom fields are not validated against a schema and can be freely added or modified.'
properties:
__typename:
type: string
name:
type:
- 'null'
- string
value:
type:
- 'null'
- string
type: object
EntryTemplate:
description: 'A template used to create new `DocumentLike` objects with pre-populated content and structure.
`EntryTemplate`s contain boilerplate text, tables, placeholders, and other note content that provides a
consistent starting point for documentation. When a new `DocumentLike` object is created from a template, the
template''s content is cloned into the new object. Templates can optionally have an `EntrySchema` to ensure
created objects capture required metadata. typeemplates belong to a `TemplateCollection` and support versioned
publishing (see `PublishingRecord`). In the UI, these are typically called "Templates" within the
Template Collections feature.'
properties:
__typename:
type: string
archiveReason:
type:
- 'null'
- string
archived:
type: boolean
createdAt:
description: DateTime the template was created at
format: datetime
type:
- 'null'
- string
creator:
description: User Resource of the user who created the template
oneOf:
- $ref: '#/components/schemas/PrincipalRef'
- type: 'null'
customFields:
oneOf:
- items:
$ref: '#/components/schemas/CustomField'
type: array
- type: 'null'
id:
description: ID of the entry template
type: string
modifiedAt:
description: DateTime the template was last modified
format: datetime
type:
- 'null'
- string
name:
description: Title of the template
type:
- 'null'
- string
schema:
description: Entry schema if set
oneOf:
- $ref: '#/components/schemas/EntrySchemaRef'
- type: 'null'
schemaFields:
oneOf:
- items:
$ref: '#/components/schemas/SchemaFieldValue'
type: array
- type: 'null'
templateCollection:
$ref: '#/components/schemas/TemplateCollectionRef'
description: Template collection that contains the template collectible
type: object
EntrySchemaRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
type: object
AnalysisTemplate:
description: 'A reusable pipeline configuration that can be instantiated to create new Analysis objects.
AnalysisTemplates define a complete data processing workflow with PipelineSteps (see `steps`)
that can be parameterized through configVariables (see `AnalysisTemplateVariable`) and
dataFrameVariables (see `AnalysisTemplateDataFrameVariable`). When users apply a template,
they provide values for these variables, generating a new Analysis with the template''s
pipeline structure populated with actual data. Templates are organized within
TemplateCollections and support versioning through the createdFromPipeline reference.'
properties:
__typename:
type: string
archivableChildren:
oneOf:
- format: uri
type: string
- type: 'null'
archivableParent:
oneOf:
- $ref: '#/components/schemas/TemplateCollectionRef'
- type: 'null'
archiveDatetime:
format: datetime
type:
- 'null'
- string
archiveReason:
type:
- 'null'
- string
archiveUser:
oneOf:
- $ref: '#/components/schemas/PrincipalRef'
- type: 'null'
archived:
type: boolean
configVariables:
format: uri
type: string
createdAt:
format: datetime
type: string
createdFromPipeline:
oneOf:
- $ref: '#/components/schemas/AnalysisRef'
- type: 'null'
creator:
$ref: '#/components/schemas/PrincipalRef'
dataFrameVariables:
format: uri
type: string
id:
type: string
modifiedAt:
format: datetime
type: string
name:
type: string
steps:
format: uri
type: string
templateCollection:
$ref: '#/components/schemas/TemplateCollectionRef'
webUrl:
type:
- 'null'
- string
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
RequestV2Definition:
description: 'A reusable template that defines the structure and configuration for requests
in Benchling. Also known as a "Request Template" in the UI. Each RequestV2Definition
specifies a `templateDocument` that serves as the document template for requests, a
`workflowTaskSchema` that defines the task structure and fields, and a `prefix` used
to generate human-readable display IDs (e.g., "REQ-001") for submissions created from
this template. Request templates are organized within `TemplateCollection` folders and
support collaboration features like starring (see `Starrable`). When users submit a
request, they create a `RequestV2Submission` based on this definition. The template
can include a `description` to explain its intended use and can be archived when no
longer needed.'
properties:
__typename:
type: string
archivableParent:
$ref: '#/components/schemas/TemplateCollectionRef'
archiveDatetime:
format: datetime
type:
- 'null'
- string
archiveReason:
type:
- 'null'
- string
archiveUser:
oneOf:
- $ref: '#/components/schemas/PrincipalRef'
- type: 'null'
archived:
type: boolean
createdAt:
format: datetime
type:
- 'null'
- string
creator:
$ref: '#/components/schemas/PrincipalRef'
description:
description: Description of the request template.
type:
- 'null'
- string
id:
type: string
modifiedAt:
format: datetime
type:
- 'null'
- string
name:
type: string
prefix:
description: The prefix for the displayId of tasks of this schema.
type: string
templateCollection:
$ref: '#/components/schemas/TemplateCollectionRef'
webUrl:
type:
- 'null'
- string
workflowTaskSchema:
$ref: '#/components/schemas/WorkflowTaskSchemaRef'
description: The task schema backing this configuration.
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
WorkflowTaskSchemaRef:
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
TemplateCollectible:
anyOf:
- $ref: '#/components/schemas/AnalysisTemplate'
- $ref: '#/components/schemas/EntrySubtemplate'
- $ref: '#/components/schemas/EntryTemplate'
- $ref: '#/components/schemas/PlateDesignTemplate'
- $ref: '#/components/schemas/Procedure'
- $ref: '#/components/schemas/RequestV2Definition'
discriminator:
propertyName: __typename
type: object
TemplateCollectibleUnpaginatedList:
additionalProperties: false
properties:
items:
items:
$ref: '#/components/schemas/TemplateCollectible'
type: array
type: object
PrincipalRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
type: object
PlateDesignTemplate:
description: 'A named plate design template backed by a scratch plate that lives in a template collection.
Plate design templates allow scratch plates to be organized and reused as templates.'
properties:
__typename:
type: string
archiveDatetime:
format: datetime
type:
- 'null'
- string
archiveReason:
type:
- 'null'
- string
archiveUser:
oneOf:
- $ref: '#/components/schemas/PrincipalRef'
- type: 'null'
archived:
type: boolean
createdAt:
format: datetime
type:
- 'null'
- string
creator:
$ref: '#/components/schemas/PrincipalRef'
id:
type: string
modifiedAt:
format: datetime
type:
- 'null'
- string
name:
type: string
scratchPlate:
$ref: '#/components/schemas/ScratchPlateRef'
templateCollection:
$ref: '#/components/schemas/TemplateCollectionRef'
webUrl:
type:
- 'null'
- 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
TemplateCollection:
description: 'A container that organizes related templates, subtemplates, and other template-like
items. Template Collections provide a way to group and manage reusable content that
teams use to create standardized entries. Each collection has an owner (typically an
Organization or Team) and can be shared with others through access controls (see
`Collaboration`). Collections can contain `EntryTemplate`s for creating new entries,
`EntrySubtemplate`s for inserting content, form definitions, procedures, and analysis
templates. In the Benchling UI, these appear in the "Template Collections" section.'
properties:
__typename:
type: string
archiveReason:
type:
- 'null'
- string
archived:
type: boolean
createdAt:
description: DateTime the template collection was created at
format: datetime
type:
- 'null'
- string
description:
description: Description of the template collection
type:
- 'null'
- string
id:
description: ID of the template collection
type: string
items:
description: All items that exist in the template collection
oneOf:
- format: uri
type: string
- type: 'null'
modifiedAt:
format: datetime
type:
- 'null'
- string
name:
description: Title of the template collection
type:
- 'null'
- string
owner:
description: Owner of the template collection
oneOf:
- $ref: '#/components/schemas/OwnerRef'
- type: 'null'
type: object
ObjectRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
type: object
AnalysisRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
type: object
TemplateCollectionPaginatedList:
additionalProperties: false
properties:
items:
items:
$ref: '#/components/schemas/TemplateCollection'
type: array
nextToken:
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
ProcedureFlowchartConfigVersionProxyRef:
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
Procedure:
description: 'A reusable template that defines a structured experimental workflow. Procedures specify a
sequence of method steps (see `ProcedureMethodDefinitionVersion`) connected in a flowchart
(see `workflowFlowchartConfig` and `WorkflowFlowchartConfigVersion`) that scientists follow when running
experiments. The `procedureType` determines whether this is a recipe (synthesis/production
workflow) or an assay (analytical workflow). Procedures belong to a `TemplateCollection` for
organization and access control, and support versioning through publishing (see `Publishable`
and `publishingRecords`). When scientists execute a procedure, they create a `ProcedureRun`
that tracks the actual experiment execution.'
properties:
__typename:
type: string
archiveDatetime:
format: datetime
type:
- 'null'
- string
archiveReason:
type:
- 'null'
- string
archiveUser:
oneOf:
- $ref: '#/components/schemas/PrincipalRef'
- type: 'null'
archived:
type: boolean
createdAt:
format: datetime
type: string
creator:
$ref: '#/components/schemas/PrincipalRef'
id:
type: string
latestProcedureFlowchartConfigVersionProxy:
description: 'A simplified view of the latest version of the flowchart config. This is the
preferred way to access the latest flowchart config for procedures.'
oneOf:
- $ref: '#/components/schemas/ProcedureFlowchartConfigVersionProxyRef'
- type: 'null'
modifiedAt:
format: datetime
type: string
name:
type: string
procedureFlowchart:
deprecated: true
description: Use latestProcedureFlowchartConfigVersionProxy for the latest flowchart version and publishedProcedureFlowchartConfigVersionProxy for the published flowchart version.
oneOf:
- $ref: '#/components/schemas/ProcedureFlowchartRef'
- type: 'null'
procedureType:
enum:
- RECIPE
- ASSAY
type: string
publishedProcedureFlowchartConfigVersionProxy:
description: 'A simplified view of the published version of the flowchart config. This is
the preferred way to access the published flowchart config for procedures.'
oneOf:
- $ref: '#/components/schemas/ProcedureFlowchartConfigVersionProxyRef'
- type: 'null'
templateCollection:
$ref: '#/components/schemas/TemplateCollectionRef'
webUrl:
type:
- 'null'
- string
type: object
TemplateCollectionRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
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
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.
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/benchling/refs/heads/main/openapi/benchling-templatecollection-api-openapi.yml