AWS Braket HybridJobs API

openapi: 3.2.0
info:
  title: AWS Braket Hybrid Jobs API
  description: 'Run hybrid quantum-classical algorithms on Amazon Braket. A hybrid job couples a containerized Python algorithm running on ML-class EC2 instances with priority access to a QPU or on-demand simulator. The job orchestrates iterative variational workloads (VQE, QAOA, QML), persists checkpoints to S3, and exposes metrics through CloudWatch.

    '
  version: 2019-09-01
  contact:
    name: AWS Support
    url: https://aws.amazon.com/contact-us/
servers:
- url: https://braket.us-east-1.amazonaws.com
  description: US East (N. Virginia)
- url: https://braket.us-west-2.amazonaws.com
  description: US West (Oregon)
- url: https://braket.eu-north-1.amazonaws.com
  description: EU (Stockholm)
security:
- SigV4: []
tags:
- name: HybridJobs
  description: Hybrid quantum-classical job orchestration.
paths:
  /job:
    post:
      summary: AWS Braket Create A Hybrid Job
      description: 'Create a hybrid job that runs a containerized algorithm against a designated QPU or simulator. Specifies the container image (or script mode with an S3 entry point), the device, instance configuration (default ml.m5.xlarge), hyperparameters, input/output channels, IAM role, and stopping condition.

        '
      operationId: createJob
      tags:
      - HybridJobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateJobRequest'
      responses:
        '201':
          description: Hybrid job created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobArn:
                    type: string
                    pattern: ^arn:aws[a-z\-]*:braket:[a-z0-9\-]+:[0-9]{12}:job/.*$
        '400':
          $ref: '#/components/responses/ValidationException'
        '403':
          $ref: '#/components/responses/AccessDeniedException'
        '409':
          $ref: '#/components/responses/ConflictException'
        '410':
          $ref: '#/components/responses/DeviceRetiredException'
        '424':
          $ref: '#/components/responses/DeviceOfflineException'
        '402':
          $ref: '#/components/responses/ServiceQuotaExceededException'
        '429':
          $ref: '#/components/responses/ThrottlingException'
        '500':
          $ref: '#/components/responses/InternalServiceException'
  /job/{jobArn}:
    get:
      summary: AWS Braket Get A Hybrid Job
      description: 'Retrieve the status, device, instance config, and checkpoint metadata for a hybrid job.

        '
      operationId: getJob
      tags:
      - HybridJobs
      parameters:
      - name: jobArn
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Hybrid job description.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
  /job/{jobArn}/cancel:
    put:
      summary: AWS Braket Cancel A Hybrid Job
      description: Cancel a hybrid job that has not yet completed.
      operationId: cancelJob
      tags:
      - HybridJobs
      parameters:
      - name: jobArn
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Cancellation accepted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  cancellationStatus:
                    type: string
                    enum:
                    - CANCELLING
                    - CANCELLED
                  jobArn:
                    type: string
  /jobs:
    post:
      summary: AWS Braket Search Hybrid Jobs
      description: Search and list hybrid jobs by status, device, creation time, or tag.
      operationId: searchJobs
      tags:
      - HybridJobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - filters
              properties:
                filters:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        enum:
                        - jobName
                        - status
                        - device
                        - createdAt
                      operator:
                        type: string
                        enum:
                        - EQUAL
                        - BETWEEN
                        - LT
                        - LTE
                        - GT
                        - GTE
                        - CONTAINS
                      values:
                        type: array
                        items:
                          type: string
                maxResults:
                  type: integer
                  minimum: 1
                  maximum: 100
                nextToken:
                  type: string
      responses:
        '200':
          description: Job search results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobs:
                    type: array
                    items:
                      $ref: '#/components/schemas/JobSummary'
                  nextToken:
                    type: string
components:
  responses:
    ValidationException:
      description: Validation failed.
      content:
        application/json:
          schema:
            type: object
    InternalServiceException:
      description: Unexpected error.
      content:
        application/json:
          schema:
            type: object
    DeviceRetiredException:
      description: Device retired.
      content:
        application/json:
          schema:
            type: object
    ConflictException:
      description: Conflicting state.
      content:
        application/json:
          schema:
            type: object
    ThrottlingException:
      description: Throttled.
      content:
        application/json:
          schema:
            type: object
    ServiceQuotaExceededException:
      description: Quota or spending limit exceeded.
      content:
        application/json:
          schema:
            type: object
    DeviceOfflineException:
      description: Device offline.
      content:
        application/json:
          schema:
            type: object
    AccessDeniedException:
      description: Caller lacks the required IAM permission.
      content:
        application/json:
          schema:
            type: object
  schemas:
    CreateJobRequest:
      type: object
      required:
      - algorithmSpecification
      - clientToken
      - deviceConfig
      - instanceConfig
      - jobName
      - outputDataConfig
      - roleArn
      properties:
        algorithmSpecification:
          type: object
          properties:
            containerImage:
              type: object
              properties:
                uri:
                  type: string
                  description: ECR URI for the algorithm container.
            scriptModeConfig:
              type: object
              properties:
                compressionType:
                  type: string
                  enum:
                  - NONE
                  - GZIP
                entryPoint:
                  type: string
                s3Uri:
                  type: string
        associations:
          type: array
          maxItems: 1
          items:
            type: object
            properties:
              arn:
                type: string
              type:
                type: string
                enum:
                - RESERVATION_TIME_WINDOW_ARN
        checkpointConfig:
          type: object
          properties:
            localPath:
              type: string
            s3Uri:
              type: string
        clientToken:
          type: string
          minLength: 1
          maxLength: 64
        deviceConfig:
          type: object
          required:
          - device
          properties:
            device:
              type: string
              description: Device ARN for the QPU/simulator used by the job.
        hyperParameters:
          type: object
          additionalProperties:
            type: string
        inputDataConfig:
          type: array
          maxItems: 20
          items:
            type: object
            properties:
              channelName:
                type: string
              contentType:
                type: string
              dataSource:
                type: object
                properties:
                  s3DataSource:
                    type: object
                    properties:
                      s3Uri:
                        type: string
        instanceConfig:
          type: object
          properties:
            instanceCount:
              type: integer
              minimum: 1
            instanceType:
              type: string
              description: SageMaker-compatible ML instance type (ml.m5.large, ml.m5.xlarge, ml.c5.4xlarge, ml.p3.8xlarge, etc.).
              default: ml.m5.xlarge
            volumeSizeInGb:
              type: integer
              minimum: 1
        jobName:
          type: string
          pattern: ^[a-zA-Z0-9](-*[a-zA-Z0-9]){0,50}$
          minLength: 1
          maxLength: 50
        outputDataConfig:
          type: object
          properties:
            kmsKeyId:
              type: string
            s3Path:
              type: string
        roleArn:
          type: string
          pattern: ^arn:aws[a-z\-]*:iam::\d{12}:role/?[a-zA-Z_0-9+=,.@\-_/]+$
        stoppingCondition:
          type: object
          properties:
            maxRuntimeInSeconds:
              type: integer
              minimum: 1
        tags:
          type: object
          additionalProperties:
            type: string
    Job:
      type: object
      properties:
        jobArn:
          type: string
        jobName:
          type: string
        status:
          type: string
          enum:
          - QUEUED
          - RUNNING
          - COMPLETED
          - FAILED
          - CANCELLING
          - CANCELLED
        deviceConfig:
          type: object
          properties:
            device:
              type: string
        instanceConfig:
          type: object
          properties:
            instanceType:
              type: string
            instanceCount:
              type: integer
            volumeSizeInGb:
              type: integer
        algorithmSpecification:
          type: object
        roleArn:
          type: string
        createdAt:
          type: string
          format: date-time
        startedAt:
          type: string
          format: date-time
        endedAt:
          type: string
          format: date-time
        billableDuration:
          type: integer
          description: Billable seconds of instance time.
        failureReason:
          type: string
        queueInfo:
          type: object
          properties:
            queue:
              type: string
            position:
              type: string
        outputDataConfig:
          type: object
        checkpointConfig:
          type: object
        tags:
          type: object
          additionalProperties:
            type: string
    JobSummary:
      type: object
      properties:
        jobArn:
          type: string
        jobName:
          type: string
        status:
          type: string
        device:
          type: string
        createdAt:
          type: string
          format: date-time
        startedAt:
          type: string
          format: date-time
        endedAt:
          type: string
          format: date-time
        tags:
          type: object
          additionalProperties:
            type: string
  securitySchemes:
    SigV4:
      type: apiKey
      name: Authorization
      in: header