openapi: 3.1.0
info:
title: AWS Braket Quantum Tasks API
description: >
Create, retrieve, search, and cancel quantum tasks on Amazon Braket. A quantum
task is a single execution of a quantum program (OpenQASM 3, AHS, or ProgramSet)
on a QPU or simulator. The API accepts an action document, target device ARN,
number of shots, and an S3 output destination, and returns a quantumTaskArn
that can be polled for status and results.
version: 2019-09-01
contact:
name: AWS Support
url: https://aws.amazon.com/contact-us/
license:
name: AWS Service Terms
url: https://aws.amazon.com/service-terms/
servers:
- url: https://braket.us-east-1.amazonaws.com
description: US East (N. Virginia)
- url: https://braket.us-west-1.amazonaws.com
description: US West (N. California)
- url: https://braket.us-west-2.amazonaws.com
description: US West (Oregon)
- url: https://braket.eu-north-1.amazonaws.com
description: EU (Stockholm)
- url: https://braket.eu-west-2.amazonaws.com
description: EU (London)
security:
- SigV4: []
tags:
- name: QuantumTasks
description: Submit and manage quantum task executions on Amazon Braket devices.
paths:
/quantum-task:
post:
summary: AWS Braket Create A Quantum Task
description: >
Create a quantum task by submitting an action document (OpenQASM 3 program,
ProgramSet, or AHS program) to be executed on a specified QPU or simulator
device. Returns the ARN of the new task; result files are written to the
S3 location supplied in outputS3Bucket and outputS3KeyPrefix.
operationId: createQuantumTask
tags:
- QuantumTasks
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateQuantumTaskRequest'
responses:
'201':
description: Quantum task created.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateQuantumTaskResponse'
'400': { $ref: '#/components/responses/ValidationException' }
'403': { $ref: '#/components/responses/AccessDeniedException' }
'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' }
/quantum-task/{quantumTaskArn}:
get:
summary: AWS Braket Get A Quantum Task
description: >
Retrieve the current state, device, shot count, and result location for a
quantum task identified by its ARN.
operationId: getQuantumTask
tags:
- QuantumTasks
parameters:
- name: quantumTaskArn
in: path
required: true
schema: { type: string, minLength: 1, maxLength: 256 }
responses:
'200':
description: Quantum task description.
content:
application/json:
schema:
$ref: '#/components/schemas/QuantumTask'
'400': { $ref: '#/components/responses/ValidationException' }
'403': { $ref: '#/components/responses/AccessDeniedException' }
'404': { $ref: '#/components/responses/ResourceNotFoundException' }
'429': { $ref: '#/components/responses/ThrottlingException' }
'500': { $ref: '#/components/responses/InternalServiceException' }
/quantum-task/{quantumTaskArn}/cancel:
put:
summary: AWS Braket Cancel A Quantum Task
description: >
Cancel a quantum task that has not yet completed. Tasks already running on
a QPU may continue until the next coherent stopping point.
operationId: cancelQuantumTask
tags:
- QuantumTasks
parameters:
- name: quantumTaskArn
in: path
required: true
schema: { type: string, minLength: 1, maxLength: 256 }
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [clientToken]
properties:
clientToken:
type: string
minLength: 1
maxLength: 64
responses:
'200':
description: Cancellation accepted.
content:
application/json:
schema:
type: object
properties:
cancellationStatus:
type: string
enum: [CANCELLING, CANCELLED]
quantumTaskArn:
type: string
'400': { $ref: '#/components/responses/ValidationException' }
'403': { $ref: '#/components/responses/AccessDeniedException' }
'404': { $ref: '#/components/responses/ResourceNotFoundException' }
'409': { $ref: '#/components/responses/ConflictException' }
'429': { $ref: '#/components/responses/ThrottlingException' }
'500': { $ref: '#/components/responses/InternalServiceException' }
/quantum-tasks:
post:
summary: AWS Braket Search Quantum Tasks
description: >
Search the caller's quantum tasks. Filters include device ARN, status,
creation time range, and tag values.
operationId: searchQuantumTasks
tags:
- QuantumTasks
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [filters]
properties:
filters:
type: array
items:
$ref: '#/components/schemas/SearchQuantumTasksFilter'
maxResults: { type: integer, minimum: 1, maximum: 100 }
nextToken: { type: string }
responses:
'200':
description: Search results.
content:
application/json:
schema:
type: object
properties:
quantumTasks:
type: array
items: { $ref: '#/components/schemas/QuantumTaskSummary' }
nextToken: { type: string }
components:
securitySchemes:
SigV4:
type: apiKey
description: AWS Signature Version 4. Sign the request with credentials for an IAM principal that has braket:* permissions.
name: Authorization
in: header
schemas:
CreateQuantumTaskRequest:
type: object
required: [action, clientToken, deviceArn, outputS3Bucket, outputS3KeyPrefix, shots]
properties:
action:
type: string
description: The serialized quantum program. Typically a JSON document conforming to braket.ir.openqasm.program, braket.ir.openqasm.program_set, or braket.ir.ahs.program.
clientToken:
type: string
description: Idempotency token unique per task.
minLength: 1
maxLength: 64
deviceArn:
type: string
description: ARN of the target QPU or simulator device. ARNs are case sensitive (e.g. arn:aws:braket:eu-north-1::device/qpu/aqt/Ibex-Q1).
minLength: 1
maxLength: 256
deviceParameters:
type: string
description: JSON-encoded provider-specific device parameters (gate set selection, noise model, etc.).
maxLength: 48000
shots:
type: integer
format: int64
description: Number of shots to execute. 0 for simulators that return statevectors.
minimum: 0
outputS3Bucket:
type: string
minLength: 3
maxLength: 63
outputS3KeyPrefix:
type: string
minLength: 1
maxLength: 1024
jobToken:
type: string
description: Optional Braket hybrid job token that associates the quantum task with a parent job.
associations:
type: array
maxItems: 1
items:
type: object
properties:
arn: { type: string }
type: { type: string, enum: [RESERVATION_TIME_WINDOW_ARN] }
experimentalCapabilities:
type: object
description: Union of experimental capabilities (e.g. pulse-level control). Only one member may be set.
tags:
type: object
additionalProperties: { type: string }
CreateQuantumTaskResponse:
type: object
properties:
quantumTaskArn: { type: string, maxLength: 256 }
QuantumTask:
type: object
properties:
quantumTaskArn: { type: string }
status:
type: string
enum: [CREATED, QUEUED, RUNNING, COMPLETED, FAILED, CANCELLING, CANCELLED]
deviceArn: { type: string }
deviceParameters: { type: string }
shots: { type: integer, format: int64 }
outputS3Bucket: { type: string }
outputS3Directory: { type: string }
createdAt: { type: string, format: date-time }
endedAt: { type: string, format: date-time }
failureReason: { type: string }
jobArn: { type: string }
queueInfo:
type: object
properties:
queue: { type: string }
position: { type: string }
tags:
type: object
additionalProperties: { type: string }
QuantumTaskSummary:
type: object
properties:
quantumTaskArn: { type: string }
deviceArn: { type: string }
status: { type: string }
shots: { type: integer, format: int64 }
createdAt: { type: string, format: date-time }
endedAt: { type: string, format: date-time }
outputS3Bucket: { type: string }
outputS3Directory: { type: string }
tags:
type: object
additionalProperties: { type: string }
SearchQuantumTasksFilter:
type: object
required: [name, operator, values]
properties:
name:
type: string
enum: [deviceArn, status, createdAt, tag]
operator:
type: string
enum: [EQUAL, BETWEEN, LT, LTE, GT, GTE]
values:
type: array
items: { type: string }
responses:
ValidationException:
description: The input request failed validation.
content:
application/json:
schema: { $ref: '#/components/schemas/Error' }
AccessDeniedException:
description: Caller lacks the required IAM permission.
content:
application/json:
schema: { $ref: '#/components/schemas/Error' }
DeviceRetiredException:
description: The targeted device has been retired.
content:
application/json:
schema: { $ref: '#/components/schemas/Error' }
DeviceOfflineException:
description: The targeted device is currently offline.
content:
application/json:
schema: { $ref: '#/components/schemas/Error' }
ConflictException:
description: Conflicting state for the resource.
content:
application/json:
schema: { $ref: '#/components/schemas/Error' }
ResourceNotFoundException:
description: The resource does not exist.
content:
application/json:
schema: { $ref: '#/components/schemas/Error' }
ServiceQuotaExceededException:
description: A service quota or spending limit was exceeded.
content:
application/json:
schema: { $ref: '#/components/schemas/Error' }
ThrottlingException:
description: The API throttling rate limit is exceeded.
content:
application/json:
schema: { $ref: '#/components/schemas/Error' }
InternalServiceException:
description: An unexpected service error.
content:
application/json:
schema: { $ref: '#/components/schemas/Error' }
# AWS Braket error envelope.
# All errors return Code + Message.