openapi: 3.2.0 info: license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html title: Benchling Test Definition API version: 2.0.0 description: 'A Test Definition is a configuration object that specifies a type of test or assay that can be ordered against samples. Each Test Definition is associated with a `ResultSchema` that defines the structure of measurement data captured when the test is performed. Test Definitions serve as templates—when a test needs to be performed on a sample, a `TestOrder` is created referencing the appropriate Test Definition. Test Definitions are used within clinical and preclinical study workflows (see `StudySampleTestPlan`) and can be linked to `Procedure` assays for execution. Belongs to an `Organization` and can be archived when no longer needed.' servers: - url: /api/v3 security: - oAuth: [] - basicApiKeyAuth: [] tags: - description: 'A Test Definition is a configuration object that specifies a type of test or assay that can be ordered against samples. Each Test Definition is associated with a `ResultSchema` that defines the structure of measurement data captured when the test is performed. Test Definitions serve as templates—when a test needs to be performed on a sample, a `TestOrder` is created referencing the appropriate Test Definition. Test Definitions are used within clinical and preclinical study workflows (see `StudySampleTestPlan`) and can be linked to `Procedure` assays for execution. Belongs to an `Organization` and can be archived when no longer needed.' name: TestDefinition x-bnch-organization: Benchling paths: /test-definition: post: description: 'Create a Test Definition that can be referenced by Test Orders and assay workflows. ## Required fields | Field | Description | | --- | --- | | `name` | Display name. Names are trimmed and must be unique within `organizationId`. | | `organizationId` | Owning organization. Use `GET /benchling/organization/items` to find organization IDs. | | `resultSchemaId` | Result schema that defines the measurements captured by this test. Use `GET /benchling/result-schema/items` to find result schema IDs. | | `description` | Human-readable description. Empty strings are allowed. | ## Notes - The creator is set automatically from the authenticated user or app. - The caller must have admin access to the organization and read access to the result schema. - `name` and `description` must each be at most 255 characters.' operationId: TestDefinition.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/CreateTestDefinitionInput' responses: '201': content: application/json: schema: $ref: '#/components/schemas/TestDefinition' 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 TestDefinition tags: - TestDefinition x-bnch-rate-limit-tier: 4 /test-definition/items: get: description: List TestDefinition items. operationId: TestDefinition.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/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/TestDefinitionPaginatedList' 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 TestDefinition items tags: - TestDefinition x-bnch-rate-limit-tier: 4 /test-definition/{test_definition_id}: get: description: Get a single TestDefinition by ID. operationId: TestDefinition.Get parameters: - description: ID of the TestDefinition. in: path name: test_definition_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/TestDefinition' 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 TestDefinition by ID tags: - TestDefinition x-bnch-rate-limit-tier: 5 patch: description: 'Update an existing Test Definition. ## Updatable fields | Field | Description | | --- | --- | | `name` | New display name. Names are trimmed and must be unique within the organization. | | `organizationId` | New owning organization. Use `GET /benchling/organization/items` to find organization IDs. | | `resultSchemaId` | New result schema. Use `GET /benchling/result-schema/items` to find result schema IDs. | | `description` | New description. Empty strings are allowed. | | `archived`, `archiveReason`, `archiveUserId` | Archive or unarchive the test definition. | ## Constraints - The caller must be able to read the target organization and result schema. - `resultSchemaId` cannot be changed after any Test Orders exist for the Test Definition. - Archiving fails if the Test Definition has pending, in-progress, or blocked Test Orders. - Archiving also fails while the Test Definition is associated with an unarchived assay. - `archiveSubtreeId` and `legacyArchiveRecordId` are legacy archival fields and should normally be omitted.' operationId: TestDefinition.Update parameters: - description: ID of the TestDefinition. in: path name: test_definition_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/UpdateTestDefinitionInput' responses: '200': content: application/json: schema: $ref: '#/components/schemas/TestDefinition' 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 TestDefinition tags: - TestDefinition x-bnch-rate-limit-tier: 4 /test-definition:batch-create: post: description: 'Batch create Test Definitions synchronously in one transaction. Maximum 25 items per request. Each item follows the same field requirements as the single-create endpoint. If any item fails validation, the transaction fails and no Test Definitions are created.' operationId: TestDefinition.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/CreateTestDefinitionInput' maxItems: 25 minItems: 1 type: array required: - items type: object responses: '201': content: application/json: schema: additionalProperties: false properties: items: items: $ref: '#/components/schemas/TestDefinition' 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 TestDefinition tags: - TestDefinition x-bnch-rate-limit-tier: 3 /test-definition:batch-update: patch: description: 'Batch update Test Definitions synchronously in one transaction. Maximum 25 items per request. Each item follows the same field requirements and archive constraints as the single-update endpoint. If any item fails validation, the transaction fails and no Test Definitions are updated.' operationId: TestDefinition.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/UpdateTestDefinitionInputWithPathParams' maxItems: 25 minItems: 1 type: array required: - items type: object responses: '200': content: application/json: schema: additionalProperties: false properties: items: items: $ref: '#/components/schemas/TestDefinition' 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 TestDefinition tags: - TestDefinition x-bnch-rate-limit-tier: 3 /test-definition:bulk-create: post: description: 'Bulk create Test Definitions asynchronously from an uploaded file. Each row follows the same field requirements as the single-create endpoint. The response returns an async task; poll the task to inspect row-level successes and validation errors.' operationId: TestDefinition.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 TestDefinition tags: - TestDefinition x-bnch-rate-limit-tier: 2 /test-definition:bulk-update: patch: description: 'Bulk update Test Definitions asynchronously from an uploaded file. Each row follows the same field requirements and archive constraints as the single-update endpoint. The response returns an async task; poll the task to inspect row-level successes and validation errors.' operationId: TestDefinition.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 TestDefinition tags: - TestDefinition x-bnch-rate-limit-tier: 2 components: 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 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 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 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 name.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. Comma-separated list. explode: false in: query name: name.anyOf schema: items: type: string maxItems: 100 type: array name.anyOf.caseSensitive: description: Restricts results to those that match any of the specified names. Case sensitive. Ensure only one name filter is used at a time. Comma-separated list. explode: false in: query name: name.anyOf.caseSensitive 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 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' description: Internal Server Error schemas: CreateTestDefinitionInput: additionalProperties: false example: description: Standard blood chemistry measurements collected for study samples. name: Blood Chemistry Panel organizationId: org_v7Q9m2Kx resultSchemaId: assaysch_Z3xY7vQb properties: description: description: Human-readable description for the test definition. Empty strings are allowed; values must be at most 255 characters. type: string name: description: Display name for the test definition. Must be non-empty after trimming whitespace and unique within the organization. type: string organizationId: description: The API ID of the organization that owns the test definition. Use `GET /benchling/organization/items` to list available organizations. type: string resultSchemaId: description: The API ID of the result schema that defines the shape of results captured for this test. Use `GET /benchling/result-schema/items` to list available result schemas. type: string required: - name - organizationId - resultSchemaId - description type: object UpdateTestDefinitionInputWithPathParams: additionalProperties: false example: archived: false description: Updated set of blood chemistry measurements collected for study samples. id: tdef_J8mQ2xY7 name: Updated Blood Chemistry Panel organizationId: org_v7Q9m2Kx resultSchemaId: assaysch_Z3xY7vQb properties: archiveReason: type: string archived: type: boolean description: description: Updated human-readable description. Empty strings are allowed; values must be at most 255 characters. type: string id: description: The API ID of the test definition to update. type: string name: description: Updated display name. When provided, it is trimmed and must be non-empty and unique within the organization. type: string organizationId: description: Updated owning organization. Use `GET /benchling/organization/items` to find organization IDs. type: string resultSchemaId: description: Updated result schema. Use `GET /benchling/result-schema/items` to find result schema IDs. Cannot be changed after test orders have been created for this test definition. type: string required: - id type: object UpdateTestDefinitionInput: additionalProperties: false example: archived: false description: Updated set of blood chemistry measurements collected for study samples. name: Updated Blood Chemistry Panel organizationId: org_v7Q9m2Kx resultSchemaId: assaysch_Z3xY7vQb properties: archiveReason: type: string archived: type: boolean description: description: Updated human-readable description. Empty strings are allowed; values must be at most 255 characters. type: string name: description: Updated display name. When provided, it is trimmed and must be non-empty and unique within the organization. type: string organizationId: description: Updated owning organization. Use `GET /benchling/organization/items` to find organization IDs. type: string resultSchemaId: description: Updated result schema. Use `GET /benchling/result-schema/items` to find result schema IDs. Cannot be changed after test orders have been created for this test definition. type: string 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 ResultSchemaRef: properties: __typename: type: string id: format: api_id type: string 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 PrincipalRef: properties: __typename: type: string id: format: api_id type: string type: object OrganizationRef: properties: __typename: type: string id: format: api_id type: string type: object TestDefinitionPaginatedList: additionalProperties: false properties: items: items: $ref: '#/components/schemas/TestDefinition' type: array nextToken: type: string type: object TestDefinition: description: 'A Test Definition is a configuration object that specifies a type of test or assay that can be ordered against samples. Each Test Definition is associated with a `ResultSchema` that defines the structure of measurement data captured when the test is performed. Test Definitions serve as templates—when a test needs to be performed on a sample, a `TestOrder` is created referencing the appropriate Test Definition. Test Definitions are used within clinical and preclinical study workflows (see `StudySampleTestPlan`) and can be linked to `Procedure` assays for execution. Belongs to an `Organization` and can be archived when no longer needed.' 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: description: Timestamp of when the test definition was created. format: datetime type: string creator: $ref: '#/components/schemas/PrincipalRef' description: The user that created the test definition. description: description: The description of the test definition. Empty strings are allowed. type: string id: description: The ID of the test definition. type: string modifiedAt: description: Timestamp of when the test definition was last modified. format: datetime type: string name: description: The name of the test definition. type: string organization: $ref: '#/components/schemas/OrganizationRef' description: The organization that owns the test definition, used for auth. resultSchema: $ref: '#/components/schemas/ResultSchemaRef' description: The result schema of the test definition, defines the measurement data shape. 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 securitySchemes: basicApiKeyAuth: description: Use issued API key for standard access to the API scheme: basic type: http basicClientIdSecretAuth: description: Auth used as part of client credentials OAuth flow prior to receiving a bearer token. scheme: basic type: http oAuth: description: OAuth2 Client Credentials flow intended for service access flows: clientCredentials: scopes: {} tokenUrl: /oauth/token type: oauth2