Rigetti Computing reservations API
Find existing time on a Rigetti QPU and reserve it.
OpenAPI Specification
openapi: 3.0.2
info:
x-logo: https://qcs.rigetti.com/static/img/rigetti-logo.svg
contact:
email: support@rigetti.com
url: https://rigetti.zendesk.com
title: Rigetti QCS account reservations API
version: 2020-07-31
description: "# Introduction\n\nThis is the documentation for the Rigetti QCS HTTP API.\n\nYou can find out more about Rigetti at [https://rigetti.com](https://rigetti.com), and also\ninteract with QCS via the web at [https://qcs.rigetti.com](https://qcs.rigetti.com).\n\nThis API is documented in **OpenAPI format** and so is compatible with the dozens of\nlanguage-specific client generators available\n[here](https://github.com/OpenAPITools/openapi-generator) and elsewhere on the web.\n\n# Principles\n\nThis API follows REST design principles where appropriate, and otherwise an HTTP RPC paradigm.\nWe adhere to the Google [API Improvement Proposals](https://google.aip.dev/general) where\nreasonable to provide a consistent, intuitive developer experience. HTTP response codes match\ntheir specifications, and error messages fit a common format.\n\n# Authentication\n\nAll access to the QCS API requires OAuth2 authentication provided by Okta. You can request\naccess [here](https://www.rigetti.com/get-quantum). Once you have a user account, you can download\nyour access token from QCS [here](https://qcs.rigetti.com/auth/token). \n\nThat access token is valid for 24 hours after issuance. The value of `access_token` within the\nJSON file is the token used for authentication (don't use the entire JSON file).\n\nAuthenticate requests using the `Authorization` header and a `Bearer` prefix:\n\n```\ncurl --header \"Authorization: Bearer eyJraW...Iow\"\n```\n\n# Quantum Processor Access\n\nAccess to the quantum processors themselves is not yet provided directly by this HTTP API, but\nis instead performed over ZeroMQ/[rpcq](https://github.com/rigetti/rpcq). Until that changes,\nwe suggest using [pyquil](https://github.com/rigetti/pyquil) to build and execute quantum\nprograms via the Legacy API.\n\n# Legacy API\n\nOur legacy HTTP API remains accessible at https://forest-server.qcs.rigetti.com, and it shares\na source of truth with this API's services. You can use either service with the same user\naccount and means of authentication. We strongly recommend using the API documented here, as the\nlegacy API is on the path to deprecation.\n"
servers:
- description: Rigetti API
url: https://api.qcs.rigetti.com
tags:
- description: Find existing time on a Rigetti QPU and reserve it.
name: reservations
x-displayName: Reservations
paths:
/v1/calendars/{quantumProcessorId}:
get:
description: Get calendar details for the requested quantum processor.
operationId: GetQuantumProcessorCalendar
parameters:
- in: path
name: quantumProcessorId
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/QuantumProcessorCalendar'
description: Request completed successfully.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Client not authorized to complete request.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: The requested quantum processor does not exist.
summary: Get Quantum Processor Calendar
tags:
- reservations
security:
- JWTBearer: []
/v1/groups/{groupName}/reservations:
get:
description: 'List existing reservations for the requested group.
Available filter fields include:
* `startTime` - timestamp
* `endTime` - timestamp
* `createdTime` - timestamp
* `price` - integer
* `quantumProcessorId` - string
Available order fields include:
* `startTime` - timestamp
* `endTime` - timestamp
* `createdTime` - timestamp
* `price` - integer
'
operationId: ListGroupReservations
parameters:
- description: URL encoded name of group for which to retrieve reservations.
in: path
name: groupName
required: true
schema:
type: string
- $ref: '#/components/parameters/filterParam'
- $ref: '#/components/parameters/orderParam'
- $ref: '#/components/parameters/pageSizeParam'
- $ref: '#/components/parameters/pageTokenParam'
- $ref: '#/components/parameters/showDeleted'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListReservationsResponse'
description: Request completed successfully.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Request authentication failed.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Request validation failed.
security:
- JWTBearer: []
summary: List Group Reservations
tags:
- reservations
/v1/reservations:
parameters: []
get:
description: 'List existing reservations for the authenticated user,
or a target user when specifying `X-QCS-ACCOUNT-ID` and `X-QCS-ACCOUNT-TYPE`
headers.
Available filter fields include:
* `startTime` - timestamp
* `endTime` - timestamp
* `createdTime` - timestamp
* `price` - integer
* `cancelled` - boolean (deprecated, use `showDeleted` parameter)
* `quantumProcessorId` - string
Available order fields include:
* `startTime` - timestamp
* `endTime` - timestamp
* `createdTime` - timestamp
* `price` - integer
'
operationId: ListReservations
parameters:
- $ref: '#/components/parameters/filterParam'
- $ref: '#/components/parameters/orderParam'
- $ref: '#/components/parameters/pageSizeParam'
- $ref: '#/components/parameters/pageTokenParam'
- $ref: '#/components/parameters/showDeleted'
- $ref: '#/components/parameters/accountIdHeader'
- $ref: '#/components/parameters/accountTypeHeader'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListReservationsResponse'
description: Request completed successfully.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Request authentication failed.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Request validation failed.
security:
- JWTBearer: []
summary: List Reservations
tags:
- reservations
post:
description: 'Create a new reservation.
The following precedence applies when specifying the reservation subject account
ID and type:
* request body `accountId` field, or if unset then `X-QCS-ACCOUNT-ID` header,
or if unset then requesting user''s ID.
* request body `accountType` field, or if unset then `X-QCS-ACCOUNT-TYPE`
header, or if unset then "user" type.
'
operationId: CreateReservation
parameters:
- $ref: '#/components/parameters/accountIdHeader'
- $ref: '#/components/parameters/accountTypeHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateReservationRequest'
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Reservation'
description: Reservation successfully created.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Request authentication failed.
'402':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Insufficient payment to book reservation.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: User not authorized to make the requested reservation.
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: The requested reservation is unavailable.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Request validation failed.
security:
- JWTBearer: []
summary: Create Reservation
tags:
- reservations
/v1/reservations/{reservationId}:
parameters:
- in: path
name: reservationId
required: true
schema:
type: integer
get:
description: Find an existing reservation by ID.
operationId: GetReservation
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Reservation'
description: Request completed successfully.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Request authentication failed.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: User not authorized to retrieve reservation.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Requested reservation does not exist.
security:
- JWTBearer: []
summary: Get Reservation
tags:
- reservations
delete:
description: Cancel an existing reservation for the user.
operationId: DeleteReservation
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Reservation'
description: Reservation successfully cancelled.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Request authentication failed.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: User not authorized to delete reservation.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Requested reservation does not exist.
security:
- JWTBearer: []
summary: Delete Reservation
tags:
- reservations
/v1/reservations:findAvailable:
parameters: []
get:
description: List currently available reservations on the requested Rigetti quantum computer.
operationId: FindAvailableReservations
parameters:
- $ref: '#/components/parameters/pageSizeParam'
- $ref: '#/components/parameters/pageTokenParam'
- in: query
name: quantumProcessorId
required: true
schema:
type: string
- in: query
name: startTimeFrom
required: true
schema:
format: date-time
type: string
- in: query
name: duration
required: true
schema:
description: Formatted as specified for golang https://golang.org/pkg/time/#ParseDuration.
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/FindAvailableReservationsResponse'
description: Request completed successfully.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Request authentication failed.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Request validation failed.
security:
- JWTBearer: []
summary: Find Available Reservations
tags:
- reservations
components:
parameters:
orderParam:
in: query
name: order
required: false
schema:
$ref: '#/components/schemas/Order'
accountTypeHeader:
description: 'Used to specify the subject account''s type for a request
in conjunction with the X-QCS-ACCOUNT-ID header.
Does not take precedence over a corresponding request body field when one
is present.
'
in: header
name: X-QCS-ACCOUNT-TYPE
schema:
$ref: '#/components/schemas/AccountType'
pageSizeParam:
in: query
name: pageSize
required: false
schema:
type: integer
showDeleted:
description: If you wish to include deleted (or cancelled) resources in your response, include `showDeleted=true`.
in: query
name: showDeleted
required: false
schema:
default: 'false'
enum:
- 'true'
- 'false'
type: string
filterParam:
in: query
name: filter
schema:
$ref: '#/components/schemas/Filter'
accountIdHeader:
description: 'Used to specify a subject account ID for a request.
Does not take precedence over a corresponding request body field when one
is present.
'
in: header
name: X-QCS-ACCOUNT-ID
schema:
$ref: '#/components/schemas/AccountId'
pageTokenParam:
description: An opaque token that can be appended to a request query to retrieve the next page of results. Empty if there are no more results to retrieve.
in: query
name: pageToken
required: false
schema:
type: string
schemas:
ValidationError:
properties:
in:
enum:
- header
- query
- path
- body
type: string
message:
title: Message
type: string
path:
items:
type: string
title: Path
type: array
required:
- in
- message
title: ValidationError
type: object
CreateReservationRequest:
properties:
accountId:
$ref: '#/components/schemas/AccountId'
accountType:
$ref: '#/components/schemas/AccountType'
endTime:
format: date-time
type: string
notes:
type: string
quantumProcessorId:
type: string
startTime:
format: date-time
type: string
required:
- quantumProcessorId
- startTime
- endTime
type: object
ListReservationsResponse:
properties:
nextPageToken:
type: string
reservations:
items:
$ref: '#/components/schemas/Reservation'
type: array
required:
- reservations
- nextPageToken
type: object
Error:
properties:
code:
title: Code
type: string
message:
title: Message
type: string
requestId:
title: Request ID
type: string
validationErrors:
items:
$ref: '#/components/schemas/ValidationError'
title: Validation Errors
type: array
required:
- code
- message
- requestId
title: Error
type: object
Filter:
description: "A string conforming to a *limited* set of the filtering operations described in [Google AIP 160](https://google.aip.dev/160).\n\n* Expressions are always of the form `{field} {operator} {value}` and may be grouped with `()` and joined with `AND` or `OR`.\n* Fields are specific to the route in question, but are typically a subset of attributes of the requested resource.\n* Operators are limited to `=`, `>`, `>=`, `<`, `<=`, and `!=`.\n* Values may take the following forms:\n * `true` or `false` for boolean fields\n * a number\n * a string (include surrounding `\"`s),\n * a duration string (include surrounding `\"`s). Valid time units are \"ns\", \"us\" (or \"µs\"), \"ms\", \"s\", \"m\", \"h\".\n * a date string (include surrounding `\"`s). Should be formatted [RFC3339 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).\n\nFor example, `startTime >= \"2020-06-24T22:00:00.000Z\" OR (duration >= \"15m\" AND endTime < \"2020-06-24T22:00:00.000Z\")`.\n"
type: string
AvailableReservation:
properties:
duration:
type: string
endTime:
format: date-time
type: string
price:
type: integer
quantumProcessorId:
type: string
startTime:
format: date-time
type: string
required:
- quantumProcessorId
- startTime
- endTime
- duration
- price
type: object
AccountId:
description: userId for `accountType` "user", group name for `accountType` "group".
type: string
FindAvailableReservationsResponse:
properties:
availableReservations:
items:
$ref: '#/components/schemas/AvailableReservation'
type: array
nextPageToken:
type: string
required:
- availableReservations
type: object
Order:
description: 'A string conforming to order specification described in [Google
AIP 132](https://google.aip.dev/132#ordering).
* Fields are specific to the route in question, but are typically a subset
of attributes of the requested resource.
* May include a comma separated list of many fields.
* Fields are sorted in *ascending* order unless the field is followed by `DESC`.
For example, `quantumProcessorId, startTime DESC`.
'
type: string
QuantumProcessorCalendar:
description: Details about calendars related to a quantum processor.
properties:
maintenanceICal:
description: This calendar's schedule contains maintenance events for the QPU, during which execution is not available.
type: string
type: object
Reservation:
properties:
accountId:
$ref: '#/components/schemas/AccountId'
accountType:
$ref: '#/components/schemas/AccountType'
cancellationBillingInvoiceItemId:
type: string
cancelled:
type: boolean
createdByAccountId:
$ref: '#/components/schemas/AccountId'
createdByAccountType:
$ref: '#/components/schemas/AccountType'
createdTime:
format: date-time
type: string
creationBillingInvoiceItemId:
type: string
endTime:
format: date-time
type: string
id:
type: integer
notes:
type: string
price:
type: integer
quantumProcessorId:
type: string
startTime:
format: date-time
type: string
updatedTime:
format: date-time
type: string
userId:
deprecated: true
description: Deprecated in favor of `accountId`.
type: string
required:
- accountId
- accountType
- id
- userId
- quantumProcessorId
- startTime
- endTime
- createdTime
- price
type: object
AccountType:
description: 'There are two types of accounts within QCS: user (representing a single user in Okta) and group (representing one or more users in Okta).'
default: user
enum:
- group
- user
type: string
securitySchemes:
JWTBearer:
bearerFormat: JWT
description: A JSON web token with `sub` or `uid` claim, as well as `groups` claim. If the token is absent, invalid or expired, the client will receive a 401 response. If the token is valid, the server uses the claims to authorize the request, which may result in a 403 response.
scheme: bearer
type: http
JWTBearerOptional:
bearerFormat: JWT
description: Same as `JWTBearer`, but the Authorization header is optionally parsed. Clients will receive a 401 response if an invalid or expired token is provided. Otherwise, the server authorizes the request against either the valid token claims or an unauthenticated user. In either case, the client may receive a 403 response.
scheme: bearer
type: http
x-tagGroups:
- name: Account Management
tags:
- account
- authentication
- name: QPU Access
tags:
- endpoints
- deployments
- engagements
- quantumProcessors
- reservations
- translation
- name: SDKs
tags:
- clientApplications
- name: Filtering and ordering
tags:
- filterParameter
- orderParameter
- name: Errors
tags:
- errors