openapi: 3.2.0 info: license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html title: Benchling App Session API version: 2.0.0 description: 'Represents a running or completed session for a Benchling App. App sessions track long-running app operations, providing status updates and user-facing messages. Each session belongs to a single app installation and progresses through a lifecycle from RUNNING to a terminal status. Sessions are updated by appending new versions, which can change the status, timeout, and displayed messages.' servers: - url: /api/v3 security: - oAuth: [] - basicApiKeyAuth: [] tags: - description: 'Represents a running or completed session for a Benchling App. App sessions track long-running app operations, providing status updates and user-facing messages. Each session belongs to a single app installation and progresses through a lifecycle from RUNNING to a terminal status. Sessions are updated by appending new versions, which can change the status, timeout, and displayed messages.' name: AppSession x-bnch-organization: Benchling paths: /app-session: post: description: Create AppSession. operationId: AppSession.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/CreateAppSessionInput' responses: '201': content: application/json: schema: $ref: '#/components/schemas/AppSession' 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 AppSession tags: - AppSession x-bnch-rate-limit-tier: 4 /app-session/items: get: description: List AppSession items. operationId: AppSession.List parameters: - $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/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/AppSessionPaginatedList' 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 AppSession items tags: - AppSession x-bnch-rate-limit-tier: 4 /app-session/{app_session_id}: get: description: Get a single AppSession by ID. operationId: AppSession.Get parameters: - description: ID of the AppSession. in: path name: app_session_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/AppSession' 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 AppSession by ID tags: - AppSession x-bnch-rate-limit-tier: 5 patch: description: Update AppSession. operationId: AppSession.Update parameters: - description: ID of the AppSession. in: path name: app_session_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/UpdateAppSessionInput' responses: '200': content: application/json: schema: $ref: '#/components/schemas/AppSession' 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 AppSession tags: - AppSession x-bnch-rate-limit-tier: 4 /app-session:batch-create: post: description: Batch create AppSession synchronously in one transaction. Maximum 25 items per request. operationId: AppSession.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/CreateAppSessionInput' maxItems: 25 minItems: 1 type: array required: - items type: object responses: '201': content: application/json: schema: additionalProperties: false properties: items: items: $ref: '#/components/schemas/AppSession' 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 AppSession tags: - AppSession x-bnch-rate-limit-tier: 3 /app-session:batch-update: patch: description: Batch update AppSession synchronously in one transaction. Maximum 25 items per request. operationId: AppSession.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/UpdateAppSessionInputWithPathParams' maxItems: 25 minItems: 1 type: array required: - items type: object responses: '200': content: application/json: schema: additionalProperties: false properties: items: items: $ref: '#/components/schemas/AppSession' 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 AppSession tags: - AppSession x-bnch-rate-limit-tier: 3 /app-session:bulk-create: post: description: Bulk create AppSession. operationId: AppSession.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 AppSession tags: - AppSession x-bnch-rate-limit-tier: 2 /app-session:bulk-update: patch: description: Bulk update AppSession. operationId: AppSession.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 AppSession tags: - AppSession x-bnch-rate-limit-tier: 2 components: schemas: IAppInstallationRef: properties: __typename: type: string id: format: api_id type: string type: object UpdateAppSessionInputWithPathParams: additionalProperties: false properties: id: type: string messages: description: Replace the current messages with this list. If omitted, the existing messages are carried forward unchanged. items: $ref: '#/components/schemas/AppSessionMessageInput' type: array status: description: Transition the session to a terminal status (SUCCEEDED, FAILED, or COMPLETED_WITH_WARNINGS). enum: - SUCCEEDED - FAILED - COMPLETED_WITH_WARNINGS type: string timeoutSeconds: description: New timeout in seconds. Must be greater than or equal to the current timeout. type: integer required: - id type: object UpdateAppSessionInput: additionalProperties: false properties: messages: description: Replace the current messages with this list. If omitted, the existing messages are carried forward unchanged. items: $ref: '#/components/schemas/AppSessionMessageInput' type: array status: description: Transition the session to a terminal status (SUCCEEDED, FAILED, or COMPLETED_WITH_WARNINGS). enum: - SUCCEEDED - FAILED - COMPLETED_WITH_WARNINGS type: string timeoutSeconds: description: New timeout in seconds. Must be greater than or equal to the current timeout. type: integer type: object CreateAppSessionInput: additionalProperties: false properties: appId: description: API ID of the Benchling App that owns this session. type: string messages: description: Initial messages to display. If omitted, the session starts with no messages. items: $ref: '#/components/schemas/AppSessionMessageInput' type: array name: description: Human-readable name for this session. type: string timeoutSeconds: description: Maximum session duration in seconds before automatic timeout (1 to 2592000). type: integer required: - appId - name - timeoutSeconds type: object AppSessionPaginatedList: additionalProperties: false properties: items: items: $ref: '#/components/schemas/AppSession' type: array nextToken: type: string type: object AppSession: description: 'Represents a running or completed session for a Benchling App. App sessions track long-running app operations, providing status updates and user-facing messages. Each session belongs to a single app installation and progresses through a lifecycle from RUNNING to a terminal status. Sessions are updated by appending new versions, which can change the status, timeout, and displayed messages.' properties: __typename: type: string app: $ref: '#/components/schemas/IAppInstallationRef' description: The Benchling App installation that owns this session. createdAt: format: datetime type: string id: type: string messages: description: The messages currently displayed to the user, from the most recent session version. items: $ref: '#/components/schemas/AppSessionMessage' type: array modifiedAt: format: datetime type: string name: type: string status: description: The current lifecycle status of this session, derived from the most recent version. enum: - RUNNING - SUCCEEDED - FAILED - COMPLETED_WITH_WARNINGS - TIMEOUT type: string timeoutSeconds: description: 'Maximum duration in seconds before the session times out automatically. Once the session''s age exceeds this value and the session has not been finalized, its status becomes TIMEOUT.' type: integer 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 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 AppSessionMessage: description: 'A status message displayed to the user within an app session. Messages convey progress, warnings, results, or errors from a running Benchling App. Each message has a textual content body and a visual style. Message content may contain inline chip references to Benchling objects using the `{id:}` syntax.' properties: __typename: type: string content: description: The text body of the message, which may contain chip references like `{id:ent_abc123}`. type: string style: description: The visual style applied to this message. enum: - NONE - INFO - WARNING - SUCCESS - ERROR type: string type: object AppSessionMessageInput: additionalProperties: false properties: content: type: string style: description: Visual style for this message. Defaults to NONE if omitted. enum: - NONE - INFO - WARNING - SUCCESS - ERROR type: string required: - content 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. explode: false in: query name: id.anyOf schema: items: type: string maxItems: 100 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 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 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.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 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 nextToken: description: Token for pagination in: query name: nextToken schema: type: string 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 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 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