openapi: 3.1.0
info:
  title: Amazon Braket API
  description: >-
    Amazon Braket is a fully managed quantum computing service that provides
    access to quantum processors, simulators, and hybrid quantum-classical
    compute through a unified API.
  version: '2019-09-01'
  contact:
    url: https://aws.amazon.com/contact-us/
  termsOfService: https://aws.amazon.com/service-terms/
externalDocs:
  description: Amazon Braket API Reference
  url: https://docs.aws.amazon.com/braket/latest/APIReference/
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-west-2.amazonaws.com
    description: EU (London)
tags:
  - name: Quantum Tasks
    description: Submit and manage quantum tasks on QPUs and simulators
  - name: Devices
    description: Discover and retrieve details about quantum devices
  - name: Jobs
    description: Manage hybrid quantum-classical jobs
  - name: Spending Limits
    description: Control QPU and simulator spending
  - name: Tags
    description: Manage resource tags
paths:
  /quantum-task:
    post:
      operationId: CreateQuantumTask
      summary: Create Quantum Task
      description: >-
        Creates a quantum task. A quantum task is a circuit or problem that
        you want to run on a quantum device. Amazon Braket queues the task
        until the device is available and returns results to the specified
        Amazon S3 location.
      tags:
        - Quantum Tasks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateQuantumTaskRequest'
      responses:
        '201':
          description: Quantum task created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateQuantumTaskResponse'
        '400':
          $ref: '#/components/responses/ValidationException'
        '403':
          $ref: '#/components/responses/AccessDeniedException'
        '429':
          $ref: '#/components/responses/ThrottlingException'
        '500':
          $ref: '#/components/responses/InternalServiceException'
  /quantum-task/{quantumTaskArn}:
    get:
      operationId: GetQuantumTask
      summary: Get Quantum Task
      description: Retrieves the details of a quantum task.
      tags:
        - Quantum Tasks
      parameters:
        - name: quantumTaskArn
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Quantum task details returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuantumTask'
        '404':
          $ref: '#/components/responses/ResourceNotFoundException'
        '429':
          $ref: '#/components/responses/ThrottlingException'
  /quantum-task/{quantumTaskArn}/cancel:
    put:
      operationId: CancelQuantumTask
      summary: Cancel Quantum Task
      description: Cancels the specified task.
      tags:
        - Quantum Tasks
      parameters:
        - name: quantumTaskArn
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - clientToken
              properties:
                clientToken:
                  type: string
      responses:
        '200':
          description: Quantum task cancellation initiated
          content:
            application/json:
              schema:
                type: object
                properties:
                  cancellationStatus:
                    type: string
                  quantumTaskArn:
                    type: string
        '400':
          $ref: '#/components/responses/ValidationException'
        '404':
          $ref: '#/components/responses/ResourceNotFoundException'
  /quantum-tasks/search:
    post:
      operationId: SearchQuantumTasks
      summary: Search Quantum Tasks
      description: Searches for tasks that match the specified filter values.
      tags:
        - Quantum Tasks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchQuantumTasksRequest'
      responses:
        '200':
          description: Quantum tasks matching filters returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchQuantumTasksResponse'
        '400':
          $ref: '#/components/responses/ValidationException'
        '429':
          $ref: '#/components/responses/ThrottlingException'
  /device/{deviceArn}:
    get:
      operationId: GetDevice
      summary: Get Device
      description: Retrieves the devices available in Amazon Braket.
      tags:
        - Devices
      parameters:
        - name: deviceArn
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Device details returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
        '404':
          $ref: '#/components/responses/ResourceNotFoundException'
        '429':
          $ref: '#/components/responses/ThrottlingException'
  /devices/search:
    post:
      operationId: SearchDevices
      summary: Search Devices
      description: Searches for devices using the specified filters.
      tags:
        - Devices
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchDevicesRequest'
      responses:
        '200':
          description: Devices matching filters returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchDevicesResponse'
        '400':
          $ref: '#/components/responses/ValidationException'
        '429':
          $ref: '#/components/responses/ThrottlingException'
  /job:
    post:
      operationId: CreateJob
      summary: Create Job
      description: >-
        Creates an Amazon Braket Hybrid Job. A hybrid job runs a classical
        algorithm with access to quantum devices for executing quantum tasks.
      tags:
        - Jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateJobRequest'
      responses:
        '201':
          description: Hybrid job created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobArn:
                    type: string
        '400':
          $ref: '#/components/responses/ValidationException'
        '409':
          $ref: '#/components/responses/ConflictException'
        '429':
          $ref: '#/components/responses/ThrottlingException'
  /job/{jobArn}:
    get:
      operationId: GetJob
      summary: Get Job
      description: Retrieves the details of a hybrid job.
      tags:
        - Jobs
      parameters:
        - name: jobArn
          in: path
          required: true
          schema:
            type: string
        - name: additionalAttributeNames
          in: query
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: Job details returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '404':
          $ref: '#/components/responses/ResourceNotFoundException'
        '429':
          $ref: '#/components/responses/ThrottlingException'
  /job/{jobArn}/cancel:
    put:
      operationId: CancelJob
      summary: Cancel Job
      description: Cancels an Amazon Braket hybrid job.
      tags:
        - Jobs
      parameters:
        - name: jobArn
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Job cancellation initiated
          content:
            application/json:
              schema:
                type: object
                properties:
                  cancellationStatus:
                    type: string
                  jobArn:
                    type: string
        '404':
          $ref: '#/components/responses/ResourceNotFoundException'
        '409':
          $ref: '#/components/responses/ConflictException'
  /jobs/search:
    post:
      operationId: SearchJobs
      summary: Search Jobs
      description: Searches for Amazon Braket hybrid jobs that match the specified filter values.
      tags:
        - Jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchJobsRequest'
      responses:
        '200':
          description: Jobs matching filters returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchJobsResponse'
        '400':
          $ref: '#/components/responses/ValidationException'
        '429':
          $ref: '#/components/responses/ThrottlingException'
  /spending-limit:
    post:
      operationId: CreateSpendingLimit
      summary: Create Spending Limit
      description: Creates a spending limit for Amazon Braket QPU or simulator usage.
      tags:
        - Spending Limits
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - maxCost
                - resourceType
                - timeRange
              properties:
                maxCost:
                  type: number
                resourceType:
                  type: string
                  enum:
                    - QPU
                    - SIMULATOR
                timeRange:
                  type: string
      responses:
        '201':
          description: Spending limit created
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/ValidationException'
  /spending-limits/search:
    post:
      operationId: SearchSpendingLimits
      summary: Search Spending Limits
      description: Searches for spending limits matching the specified filters.
      tags:
        - Spending Limits
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                maxResults:
                  type: integer
                nextToken:
                  type: string
      responses:
        '200':
          description: Spending limits returned
          content:
            application/json:
              schema:
                type: object
  /spending-limit/{spendingLimitId}:
    delete:
      operationId: DeleteSpendingLimit
      summary: Delete Spending Limit
      description: Deletes a spending limit.
      tags:
        - Spending Limits
      parameters:
        - name: spendingLimitId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Spending limit deleted
        '404':
          $ref: '#/components/responses/ResourceNotFoundException'
    patch:
      operationId: UpdateSpendingLimit
      summary: Update Spending Limit
      description: Updates an existing spending limit.
      tags:
        - Spending Limits
      parameters:
        - name: spendingLimitId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                maxCost:
                  type: number
      responses:
        '200':
          description: Spending limit updated
  /tags/{resourceArn}:
    get:
      operationId: ListTagsForResource
      summary: List Tags For Resource
      description: Lists tags for a Braket resource.
      tags:
        - Tags
      parameters:
        - name: resourceArn
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Tags returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  tags:
                    type: object
    post:
      operationId: TagResource
      summary: Tag Resource
      description: Add tags to a Braket resource.
      tags:
        - Tags
      parameters:
        - name: resourceArn
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - tags
              properties:
                tags:
                  type: object
      responses:
        '200':
          description: Tags added successfully
    delete:
      operationId: UntagResource
      summary: Untag Resource
      description: Remove tags from a Braket resource.
      tags:
        - Tags
      parameters:
        - name: resourceArn
          in: path
          required: true
          schema:
            type: string
        - name: tagKeys
          in: query
          required: true
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: Tags removed successfully
components:
  schemas:
    CreateQuantumTaskRequest:
      type: object
      required:
        - action
        - deviceArn
        - outputS3Bucket
        - outputS3KeyPrefix
        - shots
      properties:
        action:
          type: string
          description: JSON representation of the quantum circuit or annealing problem
        associations:
          type: array
          items:
            type: object
        clientToken:
          type: string
        deviceArn:
          type: string
          description: ARN of the quantum device to run the task on
        deviceParameters:
          type: string
          description: Device-specific parameters in JSON format
        jobToken:
          type: string
        outputS3Bucket:
          type: string
        outputS3KeyPrefix:
          type: string
        shots:
          type: integer
          description: Number of times to run the quantum circuit
        tags:
          type: object
    CreateQuantumTaskResponse:
      type: object
      properties:
        quantumTaskArn:
          type: string
    QuantumTask:
      type: object
      properties:
        quantumTaskArn:
          type: string
        deviceArn:
          type: string
        shots:
          type: integer
        outputS3Bucket:
          type: string
        outputS3KeyPrefix:
          type: string
        status:
          type: string
          enum:
            - CREATED
            - QUEUED
            - RUNNING
            - COMPLETED
            - FAILED
            - CANCELLING
            - CANCELLED
        failureReason:
          type: string
        createdAt:
          type: string
          format: date-time
        endedAt:
          type: string
          format: date-time
        tags:
          type: object
    SearchQuantumTasksRequest:
      type: object
      properties:
        filters:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              operator:
                type: string
              values:
                type: array
                items:
                  type: string
        maxResults:
          type: integer
        nextToken:
          type: string
    SearchQuantumTasksResponse:
      type: object
      properties:
        quantumTasks:
          type: array
          items:
            $ref: '#/components/schemas/QuantumTask'
        nextToken:
          type: string
    Device:
      type: object
      properties:
        deviceArn:
          type: string
        deviceName:
          type: string
        deviceType:
          type: string
          enum:
            - QPU
            - SIMULATOR
        deviceStatus:
          type: string
          enum:
            - ONLINE
            - OFFLINE
            - RETIRED
        providerName:
          type: string
        deviceCapabilities:
          type: string
          description: JSON string with device capabilities
    SearchDevicesRequest:
      type: object
      properties:
        filters:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              values:
                type: array
                items:
                  type: string
        maxResults:
          type: integer
        nextToken:
          type: string
    SearchDevicesResponse:
      type: object
      properties:
        devices:
          type: array
          items:
            $ref: '#/components/schemas/Device'
        nextToken:
          type: string
    CreateJobRequest:
      type: object
      required:
        - algorithmSpecification
        - clientToken
        - instanceConfig
        - jobName
        - outputDataConfig
        - roleArn
      properties:
        algorithmSpecification:
          type: object
          properties:
            containerImage:
              type: object
              properties:
                uri:
                  type: string
            scriptModeConfig:
              type: object
              properties:
                entryPoint:
                  type: string
                s3Uri:
                  type: string
                compressionType:
                  type: string
        associations:
          type: array
        checkpointConfig:
          type: object
        clientToken:
          type: string
        deviceConfig:
          type: object
          properties:
            device:
              type: string
        hyperParameters:
          type: object
        inputDataConfig:
          type: array
        instanceConfig:
          type: object
          properties:
            instanceCount:
              type: integer
            instanceType:
              type: string
            volumeSizeInGb:
              type: integer
        jobName:
          type: string
        outputDataConfig:
          type: object
          properties:
            s3Path:
              type: string
        roleArn:
          type: string
        stoppingCondition:
          type: object
          properties:
            maxRuntimeInSeconds:
              type: integer
        tags:
          type: object
    Job:
      type: object
      properties:
        jobArn:
          type: string
        jobName:
          type: string
        status:
          type: string
          enum:
            - QUEUED
            - RUNNING
            - COMPLETED
            - FAILED
            - CANCELLING
            - CANCELLED
        failureReason:
          type: string
        createdAt:
          type: string
          format: date-time
        endedAt:
          type: string
          format: date-time
        startedAt:
          type: string
          format: date-time
        billableDuration:
          type: integer
    SearchJobsRequest:
      type: object
      properties:
        filters:
          type: array
          items:
            type: object
        maxResults:
          type: integer
        nextToken:
          type: string
    SearchJobsResponse:
      type: object
      properties:
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/Job'
        nextToken:
          type: string
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
  responses:
    ValidationException:
      description: The input fails to satisfy the constraints of an Amazon Braket operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    AccessDeniedException:
      description: You do not have sufficient access to perform this action.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ResourceNotFoundException:
      description: The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ConflictException:
      description: An error occurred due to a conflict with the current state of the resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ThrottlingException:
      description: The request was throttled. Please try again later.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServiceException:
      description: The request processing has failed because of an internal error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    aws_iam:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4 authentication
security:
  - aws_iam: []