API endpoints for the OpenQASM Playground backend

The playground exposes four HTTP endpoints under /api. Every endpoint accepts JSON and returns JSON. All four endpoints proxy requests to the quasar service running on Google Cloud Run, using the GOOGLE_CLOUD_SERVICE_URL environment variable.

POST /api/simulate

Submit OpenQASM 3.0 source code and receive the quantum state vector produced by the simulator. The response lists every basis state with nonzero probability, along with its probability and complex amplitude.

Request

string

required

The full OpenQASM 3.0 program to simulate, including the OPENQASM 3.0; version declaration.

Response

State[]

required

Array of quantum basis states with nonzero probability after simulation.

Show State object properties

string[]

required

Bit string representation of this basis state, one element per declared register, in declaration order (MSB-first). For example, a 2-qubit register in the |10⟩ state yields ["10"].

number[]

required

Integer representation of each register’s bit string. A 2-qubit register in the |10⟩ state yields [2].

number

required

Probability of measuring this basis state, between 0 and 1. Probabilities across all returned states sum to 1.

object

required

Complex amplitude of this basis state.

Show amplitude properties

number

Real part of the amplitude. May be omitted if zero.

number

Imaginary part of the amplitude. May be omitted if zero.

Errors

Status	Meaning
400	The `code` field is missing, or the simulator rejected the program as invalid OpenQASM.
503	The quasar backend service is unavailable.
500	The `GOOGLE_CLOUD_SERVICE_URL` environment variable is not set, or an unexpected server error occurred.

curl --request POST \
  --url https://your-deployment.vercel.app/api/simulate \
  --header 'Content-Type: application/json' \
  --data '{
    "code": "OPENQASM 3.0;\ngate h q { U(pi/2.0, 0, pi) q; }\ngate cx c, t { ctrl @ U(pi, 0, pi) c, t; }\nqubit[2] q;\nreset q;\nh q[0];\ncx q[0], q[1];"
  }'

{
  "states": [
    {
      "binaryString": ["00"],
      "int": [0],
      "probability": 0.5,
      "amplitude": {
        "real": 0.7071067811865476
      }
    },
    {
      "binaryString": ["11"],
      "int": [3],
      "probability": 0.5,
      "amplitude": {
        "real": 0.7071067811865476
      }
    }
  ]
}

Save an OpenQASM program and receive a shareable snippet ID. The returned ID can be passed to /api/edit to retrieve the program later.

Request

string

required

The OpenQASM 3.0 program to save. The full source is stored as-is.

Response

string

required

Unique identifier for the saved snippet. Use this ID to retrieve the snippet via /api/edit.

string

required

The program source that was saved.

string

required

ISO 8601 timestamp of when the snippet was created.

Errors

Status	Meaning
400	The `code` field is missing from the request body.
500	The `GOOGLE_CLOUD_SERVICE_URL` environment variable is not set, or an unexpected server error occurred.

curl --request POST \
  --url https://your-deployment.vercel.app/api/share \
  --header 'Content-Type: application/json' \
  --data '{
    "code": "OPENQASM 3.0;\ngate h q { U(pi/2.0, 0, pi) q; }\nqubit q;\nreset q;\nh q;"
  }'

{
  "id": "abc123xyz",
  "code": "OPENQASM 3.0;\ngate h q { U(pi/2.0, 0, pi) q; }\nqubit q;\nreset q;\nh q;",
  "createdAt": "2024-11-01T12:34:56Z"
}

POST /api/edit

Retrieve a previously saved snippet by its ID. This is used by the playground to load shared programs from a URL.

Request

string

required

The snippet ID returned by a prior call to /api/share.

Response

string

required

The snippet ID.

string

required

The saved OpenQASM program source.

string

required

ISO 8601 timestamp of when the snippet was originally created.

Errors

Status	Meaning
400	The `id` field is missing from the request body.
500	The `GOOGLE_CLOUD_SERVICE_URL` environment variable is not set, the snippet was not found, or an unexpected server error occurred.

curl --request POST \
  --url https://your-deployment.vercel.app/api/edit \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "abc123xyz"
  }'

{
  "id": "abc123xyz",
  "code": "OPENQASM 3.0;\ngate h q { U(pi/2.0, 0, pi) q; }\nqubit q;\nreset q;\nh q;",
  "createdAt": "2024-11-01T12:34:56Z"
}

POST /api/validate

Check whether an OpenQASM program is syntactically valid without running a full simulation. Returns the validation result from the simulator backend.

Request

string

required

The OpenQASM 3.0 program to validate.

Response

The response body is the raw validation result returned by the quasar service. A successful validation returns an HTTP 200 with a JSON body indicating the program is valid.

Errors

Status	Meaning
400	The `code` field is missing, or the program contains a syntax error detected by the validator. The response body includes the error message from the simulator.
500	The `GOOGLE_CLOUD_SERVICE_URL` environment variable is not set, or an unexpected server error occurred.

curl --request POST \
  --url https://your-deployment.vercel.app/api/validate \
  --header 'Content-Type: application/json' \
  --data '{
    "code": "OPENQASM 3.0;\nqubit q;\nreset q;\nh q;"
  }'

{}

{
  "error": "undefined gate: h"
}

Get Started

Using the Playground

OpenQASM Examples

Reference

API endpoints for the OpenQASM Playground backend

POST /api/simulate

Request

Response

Errors

Request

Response

Errors

POST /api/edit

Request

Response

Errors

POST /api/validate

Request

Response

Errors

​POST /api/simulate

​Request

​Response

​Errors

​POST /api/share

​Request

​Response

​Errors

​POST /api/edit

​Request

​Response

​Errors

​POST /api/validate

​Request

​Response

​Errors

POST /api/simulate

Request

Response

Errors

POST /api/share

Request

Response

Errors

POST /api/edit

Request

Response

Errors

POST /api/validate

Request

Response

Errors