API Reference

QubitHub exposes a RESTful JSON API for managing quantum circuits, datasets, spaces, runs, and organizations. All endpoints are prefixed with the base URL.

Base URL

https://qubithub.co

Authentication

Most write endpoints require a JWT bearer token. See Authentication for details on obtaining tokens and managing API keys.

curl https://qubithub.co/circuits \
  -H "Authorization: Bearer <access_token>"

Response format

All responses use JSON. Paginated endpoints return a resource-specific array alongside pagination metadata:

{
  "circuits": [...],
  "total": 42,
  "page": 1,
  "pages": 3
}

The array key matches the resource type (circuits, runs, datasets, etc.).

Errors follow a consistent structure:

{
  "detail": "Error message here"
}

Common status codes

Status	Meaning
`200`	Success
`201`	Created
`204`	No content (successful delete)
`400`	Bad request (validation error, duplicate name)
`401`	Missing or invalid authentication
`403`	Insufficient permissions or usage limit exceeded
`404`	Resource not found
`409`	Conflict (e.g., fork name already exists)
`500`	Internal server error

Pagination

All list endpoints support pagination:

Parameter	Type	Default	Description
`page`	integer	`1`	Page number (1-indexed)
`limit`	integer	`20`	Items per page (1-100)

Circuits

Quantum circuits are the core resource. Each circuit has metadata, versions (file uploads), and social features (star, fork).

List circuits

GET /circuits

Public endpoint. Returns public circuits with optional filters.

Query parameters:

Parameter	Type	Description
`framework`	string	Filter by framework (`qiskit`, `pennylane`, `cirq`, `openqasm3`)
`tags`	string[]	Filter by tags (repeatable: `?tags=vqe&tags=optimization`)
`qubits_min`	integer	Minimum qubit count
`qubits_max`	integer	Maximum qubit count
`sort`	string	Sort field (default: `created_at`)
`page`	integer	Page number
`limit`	integer	Items per page

Example request:

curl "https://qubithub.co/circuits?framework=qiskit&qubits_min=2&limit=10"

Example response (200 OK):

{
  "circuits": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "bell-state",
      "slug": "bell-state",
      "title": "Bell State Circuit",
      "description": "Maximally entangled 2-qubit state",
      "framework": "qiskit",
      "tags": ["entanglement", "foundational"],
      "qubits": 2,
      "stars_count": 12,
      "views_count": 340,
      "forks_count": 3,
      "runs_count": 87,
      "is_starred": null,
      "is_public": true,
      "created_at": "2026-03-15T10:00:00",
      "updated_at": "2026-03-20T14:30:00",
      "owner": {
        "id": "660e8400-...",
        "username": "alice-q",
        "name": "Alice Quantum",
        "avatar": null
      },
      "organization": {
        "id": "770e8400-...",
        "name": "Quantum Research Lab",
        "slug": "quantum-research-lab"
      },
      "forked_from": null
    }
  ],
  "total": 42,
  "page": 1,
  "pages": 5
}

Create a circuit

POST /circuits

Requires authentication. Creates circuit metadata — file upload is a separate step.

Request body:

Field	Type	Required	Description
`name`	string	Yes	URL-safe name (lowercase, hyphens)
`title`	string	Yes	Display title
`description`	string	No	Circuit description
`framework`	string	Yes	`qiskit`, `pennylane`, `cirq`, or `openqasm3`
`tags`	string[]	No	Tags for discovery
`qubits`	integer	No	Number of qubits (default: 0)
`gates`	string[]	No	Gate names used (e.g., `["H", "CX", "RY"]`)
`depth`	integer	No	Circuit depth
`is_public`	boolean	No	Public visibility (default: true)
`organization_name`	string	No	Org slug to create under (default: personal)
`extra_metadata`	object	No	Arbitrary metadata

Example request:

curl -X POST https://qubithub.co/circuits \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "grover-search",
    "title": "Grover Search Algorithm",
    "description": "Quadratic speedup for unstructured search",
    "framework": "qiskit",
    "tags": ["search", "algorithm", "oracle"],
    "qubits": 4,
    "gates": ["H", "X", "CX", "CCX"],
    "depth": 12
  }'

Example response (201 Created):

{
  "id": "880e8400-e29b-41d4-a716-446655440000",
  "name": "grover-search",
  "slug": "grover-search",
  "title": "Grover Search Algorithm",
  "description": "Quadratic speedup for unstructured search",
  "framework": "qiskit",
  "tags": ["search", "algorithm", "oracle"],
  "qubits": 4,
  "gates": ["H", "X", "CX", "CCX"],
  "depth": 12,
  "stars_count": 0,
  "views_count": 0,
  "forks_count": 0,
  "runs_count": 0,
  "is_public": true,
  "owner": { "id": "...", "username": "alice-q", "name": "Alice Quantum" },
  "organization": null,
  "versions": [],
  "latest_version": null,
  "created_at": "2026-03-28T10:00:00",
  "updated_at": "2026-03-28T10:00:00"
}

Errors:

Status	Cause
`400`	Circuit name already exists for this user/org
`403`	Usage limit exceeded or not a member of the specified organization

Resolve circuit by name

GET /circuits/resolve?repo_name={org/circuit-name}

Look up a circuit by its full repository name (e.g., alice-q/bell-state or quantum-lab/grover-search).

Example request:

curl "https://qubithub.co/circuits/resolve?repo_name=alice-q/bell-state" \
  -H "Authorization: Bearer <access_token>"

Get circuit details

GET /circuits/{circuit_id}

Returns full circuit details including all versions. Public circuits are accessible without authentication.

Example request:

curl https://qubithub.co/circuits/550e8400-e29b-41d4-a716-446655440000

Example response (200 OK):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "bell-state",
  "slug": "bell-state",
  "title": "Bell State Circuit",
  "framework": "qiskit",
  "tags": ["entanglement"],
  "qubits": 2,
  "gates": ["H", "CX"],
  "depth": 2,
  "stars_count": 12,
  "views_count": 341,
  "forks_count": 3,
  "runs_count": 87,
  "is_starred": false,
  "is_public": true,
  "owner": { "id": "...", "username": "alice-q", "name": "Alice Quantum" },
  "organization": null,
  "forked_from": null,
  "extra_metadata": null,
  "versions": [
    {
      "id": "990e8400-...",
      "circuit_id": "550e8400-...",
      "version_number": 1,
      "commit_hash": "a1b2c3d4",
      "file_path": "circuits/550e8400.../v1/circuit.py",
      "file_size": 1234,
      "commit_message": "Initial upload",
      "created_at": "2026-03-15T10:05:00"
    }
  ],
  "latest_version": {
    "id": "990e8400-...",
    "version_number": 1,
    "commit_hash": "a1b2c3d4",
    "file_path": "circuits/550e8400.../v1/circuit.py",
    "file_size": 1234
  },
  "created_at": "2026-03-15T10:00:00",
  "updated_at": "2026-03-20T14:30:00"
}

Update a circuit

PUT /circuits/{circuit_id}

Requires authentication and ownership.

Request body (all fields optional):

Field	Type	Description
`title`	string	Display title
`description`	string	Circuit description
`tags`	string[]	Tags
`is_public`	boolean	Visibility
`extra_metadata`	object	Arbitrary metadata

Example request:

curl -X PUT https://qubithub.co/circuits/550e8400-... \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description with better explanation",
    "tags": ["entanglement", "foundational", "bell"]
  }'

Delete a circuit

DELETE /circuits/{circuit_id}

Requires authentication and ownership. Returns 204 No Content.

curl -X DELETE https://qubithub.co/circuits/550e8400-... \
  -H "Authorization: Bearer <access_token>"

Star / unstar a circuit

POST /circuits/{circuit_id}/star

Toggle star on a circuit. Requires authentication. Rate limited to 30 actions/minute.

Example response (200 OK):

{
  "starred": true,
  "stars_count": 13
}

Fork a circuit

POST /circuits/{circuit_id}/fork

Fork a circuit to your personal workspace. Requires authentication. Rate limited to 5 forks/minute.

Request body (optional):

{
  "name": "my-custom-fork-name"
}

Returns the forked circuit as a CircuitDetailResponse.

Errors:

Status	Cause
`409`	Fork name already exists
`403`	Storage quota exceeded

Upload a circuit file

POST /circuits/{circuit_id}/upload

Upload a single file to create a new version. Requires authentication and ownership. The file is sent as multipart/form-data; the commit message is a query parameter.

Parameters:

Parameter	In	Type	Required	Description
`file`	body (multipart)	file	Yes	The circuit file
`commit_message`	query	string	No	Version commit message

Example request:

curl -X POST "https://qubithub.co/circuits/550e8400-.../upload?commit_message=Add+parameterized+rotation+gates" \
  -H "Authorization: Bearer <access_token>" \
  -F "file=@circuit.py"

Batch upload files

POST /circuits/{circuit_id}/upload-batch

Upload multiple files at once (README.md, circuit.py, qubithub.toml, etc.). Same auth requirements as single upload.

List circuit files

GET /circuits/{circuit_id}/files

Returns file listing for all versions of a circuit.

List circuit runs

GET /circuits/{circuit_id}/runs

Returns execution runs for a specific circuit. See Runs for response format.

Runs

Runs represent quantum circuit executions. A run is created in PENDING status and executed asynchronously via the Dagster pipeline.

Run statuses

Status	Description
`pending`	Created, awaiting execution
`queued`	Queued in execution pipeline
`running`	Currently executing
`completed`	Finished successfully
`failed`	Execution failed
`cancelled`	Cancelled by user

Submit a run

POST /runs

Requires authentication. Creates a new run and triggers execution.

Request body:

Field	Type	Required	Description
`circuit_id`	UUID	Yes	Circuit to execute
`backend_type`	string	No	`simulation`, `emulation`, or `hardware` (default: `simulation`)
`backend_name`	string	No	Backend name (default: `qiskit_aer`)
`shots`	integer	No	Number of measurement shots, 1-100000 (default: 1024)
`parameters`	object	No	Circuit parameters (e.g., `{"theta": 0.785}`)

Example request:

curl -X POST https://qubithub.co/runs \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "circuit_id": "550e8400-e29b-41d4-a716-446655440000",
    "backend_type": "simulation",
    "backend_name": "qiskit_aer",
    "shots": 1024,
    "parameters": {"theta": 0.785398}
  }'

Example response (201 Created):

{
  "id": "aa0e8400-e29b-41d4-a716-446655440000",
  "circuit_id": "550e8400-e29b-41d4-a716-446655440000",
  "circuit_version_id": null,
  "user_id": "660e8400-...",
  "backend_type": "simulation",
  "backend_name": "qiskit_aer",
  "status": "pending",
  "shots": 1024,
  "parameters": {"theta": 0.785398},
  "results": null,
  "metrics": null,
  "error_message": null,
  "created_at": "2026-03-28T10:00:00",
  "started_at": null,
  "completed_at": null
}

Errors:

Status	Cause
`404`	Circuit not found
`403`	Access denied to private circuit, or usage limit exceeded

List runs

GET /runs

Requires authentication. Returns the current user’s runs.

Query parameters:

Parameter	Type	Description
`status`	string	Filter by status (`pending`, `queued`, `running`, `completed`, `failed`, `cancelled`)
`circuit_id`	UUID	Filter by circuit
`page`	integer	Page number
`limit`	integer	Items per page

Example request:

curl "https://qubithub.co/runs?status=completed&limit=5" \
  -H "Authorization: Bearer <access_token>"

Example response (200 OK):

{
  "runs": [
    {
      "id": "aa0e8400-...",
      "circuit_id": "550e8400-...",
      "circuit_name": "alice-q/bell-state",
      "backend_type": "simulation",
      "backend_name": "qiskit_aer",
      "status": "completed",
      "shots": 1024,
      "created_at": "2026-03-28T10:00:00",
      "completed_at": "2026-03-28T10:00:12"
    }
  ],
  "total": 42,
  "page": 1,
  "pages": 9
}

Get run details

GET /runs/{run_id}

Returns full run details including results and metrics. Accessible to the run owner or anyone if the circuit is public.

Example response (200 OK) — completed run:

{
  "id": "aa0e8400-...",
  "circuit_id": "550e8400-...",
  "circuit_version_id": "990e8400-...",
  "user_id": "660e8400-...",
  "backend_type": "simulation",
  "backend_name": "qiskit_aer",
  "status": "completed",
  "shots": 1024,
  "parameters": {"theta": 0.785398},
  "results": {
    "counts": {"00": 502, "11": 522},
    "statevector": null
  },
  "metrics": {
    "execution_time_ms": 1234,
    "transpilation_time_ms": 56
  },
  "error_message": null,
  "created_at": "2026-03-28T10:00:00",
  "started_at": "2026-03-28T10:00:01",
  "completed_at": "2026-03-28T10:00:12"
}

Cancel or delete a run

DELETE /runs/{run_id}

Requires authentication and ownership. Returns 204 No Content.

Active runs (pending/queued/running): Cancels execution, marks as cancelled
Terminal runs (completed/failed/cancelled): Deletes the record

Get your run statistics

GET /runs/users/me/stats

Requires authentication.

Example response (200 OK):

{
  "total_runs": 42,
  "pending_runs": 0,
  "queued_runs": 0,
  "running_runs": 1,
  "completed_runs": 38,
  "failed_runs": 3,
  "cancelled_runs": 0,
  "total_shots": 42368,
  "total_execution_time": 525.0,
  "avg_execution_time": 12.5,
  "success_rate": 90.5
}

Get circuit run statistics

GET /runs/circuits/{circuit_id}/stats

Returns aggregated run statistics for a specific circuit. Same response format as user stats.

Datasets

Quantum datasets for training, benchmarking, and research. Supports versioned file uploads with preview and statistics.

List datasets

GET /datasets

Public endpoint. Returns public datasets with optional filters.

Query parameters:

Parameter	Type	Description
`format`	string	Filter by format (`csv`, `npy`, `hdf5`, `json`, `parquet`)
`tags`	string[]	Filter by tags
`task_categories`	string[]	Filter by task category
`sort`	string	Sort field (default: `created_at`)
`page`	integer	Page number
`limit`	integer	Items per page

Example request:

curl "https://qubithub.co/datasets?format=csv&tags=qml"

Create a dataset

POST /datasets

Requires authentication. Creates dataset metadata — file upload happens via the versions endpoint.

Request body:

Field	Type	Required	Description
`name`	string	Yes	URL-safe name
`title`	string	Yes	Display title
`description`	string	No	Dataset description
`format`	string	Yes	Data format (`csv`, `npy`, `hdf5`, `json`, `parquet`)
`tags`	string[]	No	Tags for discovery
`task_categories`	string[]	No	ML task categories
`license`	string	No	License identifier
`citation`	string	No	Citation string
`is_public`	boolean	No	Public visibility (default: true)
`organization_name`	string	No	Org slug to create under

Example request:

curl -X POST https://qubithub.co/datasets \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "quantum-state-tomography",
    "title": "Quantum State Tomography Dataset",
    "description": "10K measurements from 2-qubit state tomography experiments",
    "format": "csv",
    "tags": ["tomography", "measurement"],
    "task_categories": ["classification"],
    "license": "CC-BY-4.0"
  }'

Get dataset details

GET /datasets/{dataset_id}

Returns full dataset details including all versions.

Update a dataset

PUT /datasets/{dataset_id}

Requires authentication and ownership. Accepts partial updates.

Delete a dataset

DELETE /datasets/{dataset_id}

Requires authentication and ownership. Returns 204 No Content.

Star / unstar a dataset

POST /datasets/{dataset_id}/star

Toggle star. Requires authentication. Rate limited to 30/minute.

Response:

{
  "starred": true,
  "stars_count": 5
}

Fork a dataset

POST /datasets/{dataset_id}/fork

Fork a dataset to your workspace. Requires authentication. Rate limited to 5/minute.

Request body (optional):

{
  "name": "my-fork-name"
}

Upload a dataset version

POST /datasets/{dataset_id}/versions

Upload a new version of the dataset file. The file is sent as multipart/form-data; the commit message is a query parameter.

Parameters:

Parameter	In	Type	Required	Description
`file`	body (multipart)	file	Yes	The dataset file
`commit_message`	query	string	No	Version description

Example request:

curl -X POST "https://qubithub.co/datasets/550e8400-.../versions?commit_message=Add+5000+new+measurements" \
  -H "Authorization: Bearer <access_token>" \
  -F "file=@data.csv"

Preview dataset

GET /datasets/{dataset_id}/preview?rows=100

Returns a preview of the first N rows (1-1000).

Example response (200 OK):

{
  "columns": ["qubit_0", "qubit_1", "label"],
  "rows": [
    [0.707, 0.293, "bell"],
    [0.500, 0.500, "ghz"]
  ],
  "total_rows": 10000,
  "dataset_schema": {
    "qubit_0": "float64",
    "qubit_1": "float64",
    "label": "string"
  }
}

Get dataset statistics

GET /datasets/{dataset_id}/stats

Returns aggregate counts for the dataset.

Example response (200 OK):

{
  "downloads_count": 142,
  "stars_count": 8,
  "forks_count": 2,
  "size_bytes": 1048576
}

Download dataset

GET /datasets/{dataset_id}/download

Downloads the latest version as a file. Increments the download counter.

Spaces

Interactive code environments for running quantum experiments. Each space contains files and supports live execution with circuit visualization.

List spaces

GET /spaces

Public endpoint.

Query parameters:

Parameter	Type	Description
`sdk`	string	Filter by SDK
`space_type`	string	Filter by type
`sort`	string	Sort field (default: `created_at`)
`page`	integer	Page number
`limit`	integer	Items per page

Create a space

POST /spaces

Requires authentication.

Request body:

Field	Type	Required	Description
`name`	string	Yes	URL-safe name
`title`	string	Yes	Display title
`description`	string	No	Space description
`sdk`	string	No	`qiskit`, `pennylane`, or `cirq` (default: `qiskit`)
`space_type`	string	No	`notebook`, `app`, or `demo` (default: `notebook`)
`is_public`	boolean	No	Public visibility (default: true)
`organization_name`	string	No	Org slug to create under

Get space details

GET /spaces/{space_id}

Returns the space with all its files.

Update a space

PUT /spaces/{space_id}

Requires authentication and ownership.

Delete a space

DELETE /spaces/{space_id}

Requires authentication and ownership. Returns 204 No Content.

Fork a space

POST /spaces/{space_id}/fork

Fork a space to your workspace. Requires authentication. Rate limited to 5/minute.

Star / unstar a space

POST /spaces/{space_id}/star

Toggle star. Requires authentication. Rate limited to 30/minute.

Manage space files

Create a file:

POST /spaces/{space_id}/files

Update a file:

PUT /spaces/files/{file_id}

Delete a file:

DELETE /spaces/files/{file_id}

All file operations require authentication and space ownership.

Execute code

POST /spaces/{space_id}/execute

Execute Python code in a sandboxed environment. Requires authentication and space ownership. The code runs in an isolated Docker container with no network access.

Request body:

Field	Type	Required	Description
`code`	string	No	Python code to execute (provide this or `file_to_run`)
`file_to_run`	string	No	Filename from space to execute instead of inline code
`timeout`	integer	No	Execution timeout in seconds (1-300, default: 30)

Example request:

curl -X POST https://qubithub.co/spaces/550e8400-.../execute \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "from qiskit import QuantumCircuit\nqc = QuantumCircuit(2)\nqc.h(0)\nqc.cx(0, 1)\nprint(qc)"
  }'

Example response (200 OK):

{
  "status": "success",
  "output": "     ┌───┐     \nq_0: ┤ H ├──■──\n     └───┘┌─┴─┐\nq_1: ─────┤ X ├\n          └───┘",
  "error": null,
  "execution_time": 1.23
}

Visualize a circuit

POST /spaces/{space_id}/visualize

Generate a circuit diagram from code. Requires authentication.

Request body:

Field	Type	Required	Description
`code`	string	No	Python code that creates a circuit (provide this or `file_to_visualize`)
`file_to_visualize`	string	No	Filename from space to visualize
`framework`	string	No	`qiskit`, `pennylane`, or `cirq` (auto-detected if omitted)

Example response (200 OK):

{
  "status": "success",
  "diagram": "PHN2ZyB4bWxucz0iaHR0cDov...",
  "framework": "qiskit",
  "format": "svg",
  "error": null
}

The diagram field contains a base64-encoded SVG string. Decode it to render the circuit diagram.

Organizations

Organizations group users and resources. Every user has a personal organization created at registration.

Get organization profile

GET /orgs/{slug}/profile

Public endpoint. Returns organization info with aggregate stats.

Example request:

curl https://qubithub.co/orgs/quantum-research-lab/profile

Example response (200 OK):

{
  "id": "770e8400-...",
  "name": "Quantum Research Lab",
  "slug": "quantum-research-lab",
  "description": "Open quantum computing research",
  "avatar_url": null,
  "created_at": "2026-03-01T10:00:00",
  "circuit_count": 15,
  "dataset_count": 3,
  "space_count": 5,
  "member_count": 4
}

List organization circuits

GET /orgs/{slug}/circuits

Public endpoint. Returns the organization’s public circuits.

Query parameters: page, limit, sort

List organization datasets

GET /orgs/{slug}/datasets

Public endpoint. Returns the organization’s public datasets.

List organization spaces

GET /orgs/{slug}/spaces

Public endpoint. Returns the organization’s public spaces.

List public members

GET /orgs/{slug}/public-members

Public endpoint. Returns members without email addresses.

Example response (200 OK):

[
  {
    "username": "alice-q",
    "full_name": "Alice Quantum",
    "avatar": null,
    "role": "owner"
  }
]

List members (authenticated)

GET /orgs/{org_id}/members

Requires authentication and organization membership. Returns full member details including emails.

Add a member

POST /orgs/{org_id}/members

Requires admin or owner role.

Request body:

Field	Type	Required	Description
`email`	string	Yes	Email of user to add
`role`	string	No	`member` (default), `admin`, or `owner`

Update member role

PATCH /orgs/{org_id}/members/{user_id}

Requires owner role.

Request body:

{
  "role": "admin"
}

Remove a member

DELETE /orgs/{org_id}/members/{user_id}

Requires admin or owner role. Returns 204 No Content. Cannot remove the last owner.

Organization API keys

GET    /orgs/{org_id}/keys
POST   /orgs/{org_id}/keys
DELETE /orgs/{org_id}/keys/{key_id}

Manage API keys scoped to an organization. Requires membership (GET) or admin/owner role (POST, DELETE).

Files

Download a file

GET /files/{file_path}

Download a circuit file from storage. The file_path is returned by GET /circuits/{circuit_id}/files. Only serves files from public circuits. Supports circuit artifacts: circuit.py, README.md, qubithub.toml, and metadata.json.

Backends

Static registry of available quantum backends.

List backends

GET /backends

Public endpoint. Returns available simulation and hardware backends.

Get calibration data

GET /backends/{backend_id}/calibration/latest

Returns the latest calibration data for a hardware backend.

Benchmarks

Quantum benchmarking suites for comparing circuit performance.

List benchmark suites

GET /benchmarks/suites

Get benchmark suite

GET /benchmarks/suites/{suite_name}

Get leaderboard

GET /benchmarks/leaderboard/{suite_name}/{problem_id}

Get your rank

GET /benchmarks/leaderboard/{suite_name}/{problem_id}/my-rank

Requires authentication.

Get featured leaderboards

GET /benchmarks/leaderboard/featured

Submit a benchmark run

POST /benchmarks/run

Requires authentication with runs:submit scope.

Query parameters:

Parameter	Type	Required	Description
`suite_name`	string	Yes	Benchmark suite to run
`problem_idx`	integer	No	Problem index within the suite (default: 0)
`circuit_idx`	integer	No	Circuit index within the suite (default: 0)
`backend`	string	No	Specific backend to test (default: all backends in suite)

WebSocket

Real-time run updates

WS /ws/runs/{run_id}
WS /ws/runs/{run_id}/subscribe

Subscribe to real-time execution updates for a run. Both paths provide the same functionality. Messages are JSON with the current status, results, and metrics as they become available.

Example (JavaScript):

const ws = new WebSocket("wss://qubithub.co/ws/runs/aa0e8400-...");

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(`Status: ${data.status}`);

  if (data.status === "completed") {
    console.log("Results:", data.results);
    ws.close();
  }
};

Python examples

Browse and run a circuit

import requests

BASE_URL = "https://qubithub.co"

# Login
auth = requests.post(f"{BASE_URL}/auth/login", json={
    "email": "alice@example.com",
    "password": "Qu4ntum!Leap#42",
})
token = auth.json()["access_token"]
headers = {"Authorization": f"Bearer {token}"}

# Find a circuit
circuits = requests.get(f"{BASE_URL}/circuits", params={
    "framework": "qiskit",
    "tags": ["entanglement"],
    "limit": 5,
}).json()

circuit_id = circuits["circuits"][0]["id"]
print(f"Found: {circuits['circuits'][0]['title']}")

# Execute it
run = requests.post(f"{BASE_URL}/runs", headers=headers, json={
    "circuit_id": circuit_id,
    "backend_type": "simulation",
    "backend_name": "qiskit_aer",
    "shots": 1024,
}).json()

print(f"Run {run['id']} — status: {run['status']}")

# Poll for results
import time
while True:
    result = requests.get(f"{BASE_URL}/runs/{run['id']}", headers=headers).json()
    if result["status"] in ("completed", "failed"):
        break
    time.sleep(2)

if result["status"] == "completed":
    print("Results:", result["results"])
else:
    print("Error:", result["error_message"])

Create and upload a circuit

import requests

BASE_URL = "https://qubithub.co"
headers = {"Authorization": "Bearer <access_token>"}

# Create circuit metadata
circuit = requests.post(f"{BASE_URL}/circuits", headers=headers, json={
    "name": "my-vqe-ansatz",
    "title": "VQE Ansatz for H2",
    "framework": "qiskit",
    "tags": ["vqe", "chemistry", "variational"],
    "qubits": 4,
    "gates": ["RY", "CX"],
}).json()

circuit_id = circuit["id"]

# Upload circuit file
with open("circuit.py", "rb") as f:
    requests.post(
        f"{BASE_URL}/circuits/{circuit_id}/upload",
        headers=headers,
        files={"file": f},
        params={"commit_message": "Initial VQE ansatz implementation"},
    )

print(f"Circuit uploaded: {circuit['name']}")

Work with datasets

import requests

BASE_URL = "https://qubithub.co"
headers = {"Authorization": "Bearer <access_token>"}

# Create a dataset
dataset = requests.post(f"{BASE_URL}/datasets", headers=headers, json={
    "name": "h2-energy-landscape",
    "title": "H2 Energy Landscape",
    "format": "csv",
    "tags": ["chemistry", "vqe"],
    "task_categories": ["regression"],
}).json()

# Upload data file
with open("data.csv", "rb") as f:
    requests.post(
        f"{BASE_URL}/datasets/{dataset['id']}/versions",
        headers=headers,
        files={"file": f},
        params={"commit_message": "Initial dataset with 10K bond distances"},
    )

# Preview the dataset
preview = requests.get(
    f"{BASE_URL}/datasets/{dataset['id']}/preview",
    params={"rows": 5},
).json()

print(f"Columns: {preview['columns']}")
print(f"Total rows: {preview['total_rows']}")

Rate limits

Resource	Limit
API requests	60/min (Free), 600/min (Pro)
Star actions	30/min per user
Fork actions	5/min per user

When you exceed a rate limit, the API returns 429 Too Many Requests. Back off and retry after a short delay.

Next steps

Authentication — JWT tokens, API keys, and security
qubithub.toml Reference — circuit manifest specification
CLI Quickstart — manage circuits from the command line
FAQ — common questions and answers