openapi: 3.1.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:
securitySchemes:
SigV4:
type: apiKey
name: Authorization
in: header
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 }
responses:
ValidationException:
description: Validation failed.
content: { application/json: { schema: { type: object } } }
AccessDeniedException:
description: Caller lacks the required IAM permission.
content: { application/json: { schema: { type: object } } }
ConflictException:
description: Conflicting state.
content: { application/json: { schema: { type: object } } }
DeviceRetiredException:
description: Device retired.
content: { application/json: { schema: { type: object } } }
DeviceOfflineException:
description: Device offline.
content: { application/json: { schema: { type: object } } }
ServiceQuotaExceededException:
description: Quota or spending limit exceeded.
content: { application/json: { schema: { type: object } } }
ThrottlingException:
description: Throttled.
content: { application/json: { schema: { type: object } } }
InternalServiceException:
description: Unexpected error.
content: { application/json: { schema: { type: object } } }