Rigetti QCS API

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 API
  version: 2020-07-31
  description: >
    # Introduction


    This is the documentation for the Rigetti QCS HTTP API.


    You can find out more about Rigetti at [https://rigetti.com](https://rigetti.com), and also

    interact with QCS via the web at [https://qcs.rigetti.com](https://qcs.rigetti.com).


    This API is documented in **OpenAPI format** and so is compatible with the dozens of

    language-specific client generators available

    [here](https://github.com/OpenAPITools/openapi-generator) and elsewhere on the web.


    # Principles


    This API follows REST design principles where appropriate, and otherwise an HTTP RPC paradigm.

    We adhere to the Google [API Improvement Proposals](https://google.aip.dev/general) where

    reasonable to provide a consistent, intuitive developer experience. HTTP response codes match

    their specifications, and error messages fit a common format.


    # Authentication


    All access to the QCS API requires OAuth2 authentication provided by Okta. You can request

    access [here](https://www.rigetti.com/get-quantum). Once you have a user account, you can download

    your access token from QCS [here](https://qcs.rigetti.com/auth/token). 


    That access token is valid for 24 hours after issuance. The value of `access_token` within the

    JSON file is the token used for authentication (don't use the entire JSON file).


    Authenticate requests using the `Authorization` header and a `Bearer` prefix:


    ```

    curl --header "Authorization: Bearer eyJraW...Iow"

    ```


    # Quantum Processor Access


    Access to the quantum processors themselves is not yet provided directly by this HTTP API, but

    is instead performed over ZeroMQ/[rpcq](https://github.com/rigetti/rpcq). Until that changes,

    we suggest using [pyquil](https://github.com/rigetti/pyquil) to build and execute quantum

    programs via the Legacy API.


    # Legacy API


    Our legacy HTTP API remains accessible at https://forest-server.qcs.rigetti.com, and it shares

    a source of truth with this API's services. You can use either service with the same user

    account and means of authentication. We strongly recommend using the API documented here, as the

    legacy API is on the path to deprecation.
servers:
  - description: Rigetti API
    url: https://api.qcs.rigetti.com
tags:
  - description: Internal Rigetti administrative Access
    name: internal
    x-displayName: Internal
  - description: Legacy routes and objects
    name: legacy
    x-displayName: Legacy
  - description: The Quantum Processor is the heart of the Rigetti services.
    name: quantumProcessors
    x-displayName: Quantum Processors
  - description: Deployments manage Controller Services and supporting services.
    name: deployments
    x-displayName: Quantum Processor Deployments
  - description: The Endpoint is the means of access to a Quantum Processor.
    name: endpoints
    x-displayName: Quantum Processor Endpoints
  - description: The Engagement is the authorization mechanism for access to the
      Quantum Processor.
    name: engagements
    x-displayName: Engagements
  - description: |
      Translation is the process of transforming Quil into programs ready 
      for execution on a Quantum Processor.
    name: translation
    x-displayName: Translation
  - name: account
    x-displayName: Account
  - name: authentication
    x-displayName: Authentication
  - description: Check for the latest SDK versions.
    name: clientApplications
    x-displayName: SDK Versions
  - description: Find existing time on a Rigetti QPU and reserve it.
    name: reservations
    x-displayName: Reservations
  - name: filterParameter
    description: <SchemaDefinition schemaRef="#/components/schemas/Filter" />
    x-displayName: Filter Parameter
  - name: orderParameter
    description: <SchemaDefinition schemaRef="#/components/schemas/Order" />
    x-displayName: Order Parameter
  - name: errors
    description: >
      All service errors conform to the below schema.


      <SchemaDefinition schemaRef="#/components/schemas/Error" />


      `code` conforms to the conventional HTTP status code, but offers more granularity.


      | Code                                | HTTP Status Code | Notes                                                                               |

      |-------------------------------------|------------------|-------------------------------------------------------------------------------------|

      | unauthorized                        | 401              | If your token expires, we will return a 401 and you should refresh it accordingly\. |

      | forbidden                           | 403              |                                                                                     |

      | not\_found                          | 404              |                                                                                     |

      | insufficient\_payment               | 402              | Insufficient funds are available to book the reservation\.                          |

      | reservation\_unavailable            | 409              | The requested reservation time is not available\.                                   |

      | invalid\_input                      | 422              |                                                                                     |

      | invalid\_password\_reset\_token     | 422              |                                                                                     |

      | invalid\_email\_verification\_token | 422              |                                                                                     |


      Additionally, errors returned with code `invalid_input` *may* include additional detail under the `validationErrors`

      attribute. Note, not all validation errors will specify a `path`, but they will contain a message. Please heed those

      messages *in addition to* the top level error message.


      <SchemaDefinition schemaRef="#/components/schemas/ValidationError" />
    x-displayName: ""
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
paths:
  /:
    get:
      description: Retrieve the health status of the API
      operationId: GetHealth
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Health"
          description: Critical services are healthy.
  /v1/:
    get:
      deprecated: true
      description: Endpoint to return a status 200 for load balancer health checks
      operationId: HealthCheckDeprecated
      responses:
        "200":
          content:
            application/json:
              schema: {}
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
          description: Unprocessable Entity
      summary: Health Check
  /v1/endpoints:
    get:
      description: List all endpoints, optionally filtering by attribute.
      operationId: ListEndpoints
      parameters:
        - description: Filtering logic specified using
            [rule-engine](https://zerosteiner.github.io/rule-engine/syntax.html)
            grammar
          in: query
          name: filter
          required: false
          schema:
            description: Filtering logic specified using
              [rule-engine](https://zerosteiner.github.io/rule-engine/syntax.html)
              grammar
            title: Filter
            type: string
        - in: query
          name: pageSize
          required: false
          schema:
            default: 10
            title: Pagesize
            type: integer
        - in: query
          name: pageToken
          required: false
          schema:
            title: Pagetoken
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListEndpointsResponse"
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
          description: Unprocessable Entity
      security:
        - JWTBearer: []
      summary: List Endpoints
      tags:
        - endpoints
    post:
      description: Create an endpoint associated with your user account.
      operationId: CreateEndpoint
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateEndpointParameters"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Endpoint"
          description: Successful Response
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
          description: Bad Request
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
          description: Not Found
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
          description: Unprocessable Entity
      security:
        - JWTBearer: []
      summary: Create Endpoint
      tags:
        - endpoints
  "/v1/endpoints/{endpointId}":
    delete:
      description: Delete an endpoint, releasing its resources. This operation is not
        reversible.
      operationId: DeleteEndpoint
      parameters:
        - in: path
          name: endpointId
          required: true
          schema:
            title: Endpoint ID
            type: string
      responses:
        "204":
          description: Successful Response
        "403":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
          description: Forbidden
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
          description: Not Found
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
          description: Unprocessable Entity
      security:
        - JWTBearer: []
      summary: Delete Endpoint
      tags:
        - endpoints
    get:
      description: Retrieve a specific endpoint by its ID.
      operationId: GetEndpoint
      parameters:
        - in: path
          name: endpointId
          required: true
          schema:
            title: Endpoint ID
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Endpoint"
          description: Successful Response
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
          description: Not Found
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
          description: Unprocessable Entity
      security:
        - JWTBearer: []
      summary: Get Endpoint
      tags:
        - endpoints
  "/v1/endpoints/{endpointId}:restart":
    post:
      description: Restart an entire endpoint or a single component within an endpoint.
      operationId: RestartEndpoint
      parameters:
        - in: path
          name: endpointId
          required: true
          schema:
            title: Endpoint ID
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RestartEndpointRequest"
      responses:
        "204":
          description: Successful Response
        "403":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
          description: Forbidden
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
          description: Unprocessable Entity
      security:
        - JWTBearer: []
      summary: Restart Endpoint
      tags:
        - endpoints
  /v1/engagements:
    post:
      description: >-
        Create a new engagement using the specified parameters.


        At least one of the following parameters must be supplied:

        - **endpointId**: The ID of the endpoint on which to engage.

        - **quantumProcessorId**: The ID of the quantum processor on which to engage, allowing the
            service to select a default endpoint. Ignored if **endpointId** is set.
      operationId: CreateEngagement
      parameters:
        - description: Either the client's user ID or the name of a group on behalf of
            which the client wishes to engage. May be overriden by accountId set
            in body.
          in: header
          name: x-qcs-account-id
          required: false
          schema:
            description: Either the client's user ID or the name of a group on behalf of
              which the client wishes to engage. May be overriden by accountId
              set in body.
            title: X-Qcs-Account-Id
            type: string
        - description: Indicates whether the engagement request should be made for the
            user or on behalf of a group. May be overriden by accountType set in
            body.
          in: header
          name: x-qcs-account-type
          required: false
          schema:
            allOf:
              - $ref: "#/components/schemas/AccountType"
            description: Indicates whether the engagement request should be made for the
              user or on behalf of a group. May be overriden by accountType set
              in body.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateEngagementRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EngagementWithCredentials"
          description: Successful Response
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
          description: Bad Request
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
          description: Not Found
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
          description: Validation error
        "503":
          description: Endpoint is temporarily unavailable, try again later.
          headers:
            Retry-After:
              description: Number of seconds to wait before retrying
              schema:
                type: integer
      security:
        - JWTBearer: []
      summary: Create Engagement
      tags:
        - engagements
  "/v1/quantumProcessors/{quantumProcessorId}/endpoints:getDefault":
    get:
      description: |-
        Retrieve the endpoint set as "default" for the given Quantum Processor.

        If no endpoint is set as the default, return "not found."
      operationId: GetDefaultEndpoint
      parameters:
        - description: "Public identifier for a quantum processor [example: Aspen-1]"
          in: path
          name: quantumProcessorId
          required: true
          schema:
            description: "Public identifier for a quantum processor [example: Aspen-1]"
            title: Quantum Processor ID
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Endpoint"
          description: Successful Response
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
          description: Not Found
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
          description: Unprocessable Entity
      security:
        - JWTBearer: []
      summary: Get Default Endpoint
      tags:
        - endpoints
  "/v1/quantumProcessors/{quantum_processor_id}":
    get:
      tags:
        - quantumProcessors
      summary: Get Quantum Processor
      description: Retrieve a single `QuantumProcessor` by ID.
      parameters:
        - name: quantum_processor_id
          schema:
            type: string
          in: path
          required: true
          deprecated: false
          explode: true
      responses:
        "200":
          description: ""
          content:
            application/json; charset=utf-8:
              schema:
                $ref: "#/components/schemas/QuantumProcessor"
        "422":
          description: User-provided data failed validation
          content:
            application/json; charset=utf-8:
              schema:
                $ref: "#/components/schemas/ValidationError"
        default:
          description: Some other error
          content:
            application/json; charset=utf-8:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - JWTBearerOptional: []
      operationId: GetQuantumProcessor
  /v1/quantumProcessors:
    get:
      tags:
        - quantumProcessors
      summary: List Quantum Processors
      description: |-
        List the [`QuantumProcessor`]s that this user is authorized to access.

        If no auth token is provided, only public processors will be returned.
      parameters:
        - name: pageSize
          schema:
            type: integer
            format: uint64
            title: How many items to return in a single page.
            default: 10
            minimum: 0
            exclusiveMinimum: true
          in: query
          required: false
          deprecated: false
          explode: true
        - name: pageToken
          schema:
            type: string
            title: A page token to continue pagination across requests.
          in: query
          required: false
          deprecated: false
          explode: true
      responses:
        "200":
          description: ""
          content:
            application/json; charset=utf-8:
              schema:
                $ref: "#/components/schemas/ListQuantumProcessorsResponse"
        "422":
          description: User-provided data failed validation
          content:
            application/json; charset=utf-8:
              schema:
                $ref: "#/components/schemas/ValidationError"
        default:
          description: Some other error
          content:
            application/json; charset=utf-8:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - JWTBearerOptional: []
      operationId: ListQuantumProcessors
  "/v1/quantumProcessors/{quantum_processor_id}/accessors":
    get:
      tags:
        - quantumProcessors
      summary: Get Quantum Processor Accessors
      description: Retrieve a single `QuantumProcessor` by ID.
      parameters:
        - name: quantum_processor_id
          schema:
            type: string
          in: path
          required: true
          deprecated: false
          explode: true
      responses:
        "200":
          description: ""
          content:
            application/json; charset=utf-8:
              schema:
                $ref: "#/components/schemas/ListQuantumProcessorAccessorsResponse"
        "422":
          description: User-provided data failed validation
          content:
            application/json; charset=utf-8:
              schema:
                $ref: "#/components/schemas/ValidationError"
        default:
          description: Some other error
          content:
            application/json; charset=utf-8:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - JWTBearerOptional: []
      operationId: GetQuantumProcessorAccessors
  "/v1/quantumProcessors/{quantum_processor_id}/instructionSetArchitecture":
    get:
      tags:
        - quantumProcessors
      summary: Get Instruction Set Architecture
      parameters:
        - name: quantum_processor_id
          schema:
            type: string
          in: path
          required: true
          deprecated: false
          explode: true
      responses:
        "200":
          description: ""
          content:
            application/json; charset=utf-8:
              schema:
                $ref: "#/components/schemas/InstructionSetArchitecture"
        "422":
          description: User-provided data failed validation
          content:
            application/json; charset=utf-8:
              schema:
                $ref: "#/components/schemas/ValidationError"
        default:
          description: Some other error
          content:
            application/json; charset=utf-8:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - JWTBearerOptional: []
      operationId: GetInstructionSetArchitecture
  /v1/instructionSetArchitectures:
    get:
      tags:
        - quantumProcessors
      summary: List Instruction Set Architectures
      parameters:
        - name: pageSize
          schema:
            type: integer
            format: uint64
            title: How many items to return in a single page.
            default: 5
            maximum: 5
            minimum: 0
            exclusiveMinimum: true
          in: query
          required: false
          deprecated: false
          explode: true
        - name: pageToken
          schema:
            type: string
            title: A page token to continue pagination across requests.
          in: query
          required: false
          deprecated: false
          explode: true
      responses:
        "200":
          description: ""
          content:
            application/json; charset=utf-8:
              schema:
                $ref: "#/components/schemas/ListInstructionSetArchitectureResponse"
        "422":
          description: User-provided data failed validation
          content:
            application/json; charset=utf-8:
              schema:
                $ref: "#/components/schemas/ValidationError"
        default:
          description: Some other error
          content:
            application/json; charset=utf-8:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - JWTBearerOptional: []
      operationId: ListInstructionSetArchitectures
  /v1/healthcheck:
    get:
      summary: Health Check
      description: Check the health of the service.
      responses:
        "200":
          description: The service is healthy, but there are no additional details.
      operationId: HealthCheck
  /v1/auth:emailPasswordResetToken:
    post:
      description: Send a password reset link to the provided email address, if that
        email matches a registered user.
      operationId: AuthEmailPasswordResetToken
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AuthEmailPasswordResetTokenRequest"
      responses:
        "204":
          description: Request completed successfully.
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
          description: Request validation failed.
      summary: Email Password Reset Token
      tags:
        - authentication
  /v1/auth:getUser:
    get:
      description: Retrieve the profile of the authenticated user.
      operationId: AuthGetUser
      parameters: []
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
          description: Request completed successfully.
        "401":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
          description: Request authentication failed.
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
          description: The authenticated user could not be located within our records.
            Please contact support@rigetti.com if you reach this error.
      security:
        - JWTBearer: []
      summary: Get User
      tags:
        - authentication
  /v1/auth:resetPassword:
    parameters: []
    post:
      description: Reset the password using the user's existing password. Note, this
        is an authenticated route.
      operationId: AuthResetPassword
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AuthResetPasswordRequest"
        required: true
      responses:
        "204":
          description: Password successfully reset.
        "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: Reset Password
      tags:
        - authentication
  /v1/auth:resetPasswordWithToken:
    parameters: []
    post:
      description: Complete the forgot password flow, resetting the new password in
        exchange for an emailed token.
      operationId: AuthResetPasswordWithToken
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AuthResetPasswordWithTokenRequest"
        required: true
      responses:
        "204":
          description: Password successfully reset.
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
          description: No account exists for the requested email.
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
          description: Request validation failed.
      summary: Reset Password With Token
      tags:
        - authentication
  "/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/clientApplications:
    get:
      description: List supported clients of Rigetti system components along with
        their latest and minimum supported versions.
      operationId: ListClientApplications
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListClientApplicationsResponse"
          description: Request completed successfully.
      summary: List Client Applications
      tags:
        - clientApplications
    parameters: []
  "/v1/clientApplications/{clientApplicationName}":
    get:
      description: Get details of a specific Rigetti system component along with its
        latest and minimum supported versions.
      operationId: GetClientApplication
      parameters:
        - in: path
          name: clientApplicationName
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientApplication"
          description: Request completed successfully.
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
          description: The requested client application does not exist.
      summary: Get Client Application
      tags:
        - clientApplications
  /v1/clientApplications:check:
    post:
      description: Check the requested client application version against the latest
        and minimum version.
      operationId: CheckClientApplication
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CheckClientApplicationRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CheckClientApplicationResponse"
          description: Successfully checked Forest versions.
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
          description: Requested component does not exist.
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
          description: Request validation failed.
      summary: Check Client Application
      tags:
        - clientApplications
  "/v1/groups/{groupName}/balance":
    get:
      description: Retrieve the balance of the requested QCS group account.
      operationId: GetGroupBalance
      parameters:
        - description: URL encoded name of group for which to retrieve account balance.
          in: path
          name: groupName
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountBalance"
          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: QCS group account does not exist.
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
          description: Request validation failed.
      security:
        - JWTBearer: []
      summary: Get Group Balance
      tags:
        - account
  "/v1/groups/{groupName}/billingCustomer":
    get:
      description: Retrieve billing customer for a QCS group account.
      operationId: GetGroupBillingCustomer
      parameters:
        - description: URL-encoded name of group.
       

# --- truncated at 32 KB (114 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/rigetti/refs/heads/main/openapi/rigetti-qcs-api-openapi.yml