### Install Quantum Client SDK

Source: https://docs.hub.kipu-quantum.com/sdk-quantum-client-reference.html

Installs or upgrades the Quantum Client SDK for Python. Ensure you have Python 3.11 or higher installed.

```bash
pip install --upgrade qhub-api
```

--------------------------------

### Installation

Source: https://docs.hub.kipu-quantum.com/sdk-api-reference.html

Instructions for installing the Kipu Quantum Hub API SDK for Python.

```APIDOC
## Installation

### Python

Install the API SDK using `pip`:

```bash
uv add qhub-api
# OR with native pip
pip install --upgrade qhub-api
```
```

--------------------------------

### Explore Quantum Backends

Source: https://docs.hub.kipu-quantum.com/sdk-quantum-client-reference.html

Provides Python code examples for discovering and retrieving information about available quantum backends. This includes listing all backends, getting detailed information for a specific backend, checking its status, and fetching calibration data for physical hardware.

```python
# List all available backends
backends = client.backends.get_backends()
for backend in backends:
    print(f"{backend.id} - {backend.name}")

# Get detailed backend information
backend_info = client.backends.get_backend("aws.ionq.aria")
print(f"Backend: {backend_info.name}")
print(f"Qubits: {backend_info.configuration.qubit_count}")

# Check backend status and availability
status = client.backends.get_backend_status("azure.ionq.simulator")
print(f"Status: {status.status}")

# Get backend calibration data (for physical quantum hardware that supports it)
calibration = client.backends.get_backend_calibration("aws.ionq.aria")
print(f"Backend ID: {calibration.backend_id}")
```

--------------------------------

### Install Service SDK with pip

Source: https://docs.hub.kipu-quantum.com/sdk-reference-service.html

Installs the Service SDK using pip, including the recommended step of creating and activating a virtual environment.

```bash
# Create a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the package
pip install qhub-service
```

--------------------------------

### Install Quantum SDK using pip

Source: https://docs.hub.kipu-quantum.com/tutorials/tutorial-qiskit-with-platform-sdk.html

Installs the Quantum SDK package from PyPI. Requires Python 3.11 or higher. This command is executed in the terminal or command prompt.

```bash
pip install qhub-quantum
```

--------------------------------

### Initialize Project with qhubctl

Source: https://docs.hub.kipu-quantum.com/services/managed/datapool.html

Initializes a new service project using the qhubctl CLI, sets up a virtual environment, and installs dependencies.

```bash
qhubctl init

cd [user_code]

uv venv
source .venv/bin/activate
uv sync
```

--------------------------------

### Initialize Python Quantum Project

Source: https://docs.hub.kipu-quantum.com/quickstart.html

Steps to create a project directory, initialize a virtual environment with uv, and install the Quantum SDK.

```bash
mkdir ~/my-quantum-project
cd ~/my-quantum-project
uv venv
uv init
source .venv/bin/activate
uv add qhub-quantum
```

--------------------------------

### Install Kipu Quantum Hub API SDK

Source: https://docs.hub.kipu-quantum.com/sdk-api-reference.html

Instructions for installing the Kipu Quantum Hub API SDK using pip for Python. It ensures you have the necessary tools to interact with the Kipu Quantum Hub platform.

```bash
uv add qhub-api
# OR with native pip
pip install --upgrade qhub-api
```

--------------------------------

### Set Up Python Client Environment

Source: https://docs.hub.kipu-quantum.com/tutorials/tutorial-datapool.html

Commands to initialize a project directory, set up a virtual environment using uv, and install necessary dependencies for the Kipu Quantum service client.

```bash
cd ..
mkdir text-analyzer-client
cd text-analyzer-client
uv init && uv sync -U
uv add qhub-service python-dotenv
source .venv/bin/activate
```

--------------------------------

### Install and Verify Quantum Hub CLI

Source: https://docs.hub.kipu-quantum.com/tutorials/tutorial-datapool.html

Installs the latest version of the Quantum Hub CLI using npm and verifies the installation by checking the CLI version. Requires Node.js 20+.

```bash
npm install -g @quantum-hub/qhubctl

qhubctl --version
```

--------------------------------

### Install and Configure Kipu Quantum Hub CLI

Source: https://docs.hub.kipu-quantum.com/quickstart.html

Commands to install the CLI globally via npm and authenticate the user session using a personal access token.

```bash
npm install -g @quantum-hub/qhubctl
qhubctl login -t <your access token>
```

--------------------------------

### POST /

Source: https://docs.hub.kipu-quantum.com/files/openapi/openapi-service.yaml

Starts a new asynchronous service execution.

```APIDOC
## POST /

### Description
Starts a service execution, which in turn is processed asynchronously. The location header of the response contains the URL which can be used to query the status and the result of the service execution.

### Method
POST

### Endpoint
/

### Request Body
- **data** (object) - Required - The input parameters for the service execution.

### Response
#### Success Response (201)
- **Location** (string) - URL to query the status and the result of a service execution.

#### Response Example
{ "id": "exec-456", "status": "PENDING" }
```

--------------------------------

### Example qhub.json Configuration

Source: https://docs.hub.kipu-quantum.com/qhub-json-reference.html

This snippet demonstrates the structure of a complete qhub.json file. It includes required fields such as service name, resource allocation, and runtime selection.

```json
{
  "name": "my-service",
  "descriptionFile": "README.md",
  "resources": {
    "cpu": 2,
    "memory": 4,
    "gpu": {
      "type": "NVIDIA_TESLA_T4",
      "count": 1
    }
  },
  "runtime": "PYTHON_TEMPLATE",
  "serviceId": "99487f0b-21f0-4256-8335-5179d416dbb4"
}
```

--------------------------------

### Install QHub CLI globally

Source: https://docs.hub.kipu-quantum.com/tutorials/tutorial-local-development.html

Installs the QHub command line interface globally using npm. This is a prerequisite for managing services from the terminal.

```bash
npm install -g @quantum-hub/qhubctl
```

--------------------------------

### Install Kipu Quantum Hub CLI

Source: https://docs.hub.kipu-quantum.com/cli-reference.html

Installs the Kipu Quantum Hub CLI globally using npm. Requires Node.js 20 or higher.

```bash
npm i -g @quantum-hub/qhubctl
```

--------------------------------

### Navigate to project and start local service

Source: https://docs.hub.kipu-quantum.com/tutorials/tutorial-local-development.html

Commands to navigate to the project directory and initiate the local service environment. The service becomes accessible at http://localhost:8081 upon execution.

```bash
cd my-project
qhubctl serve
```

--------------------------------

### Basic Service SDK Execution Example

Source: https://docs.hub.kipu-quantum.com/sdk-reference-service.html

Demonstrates the basic usage of the Service SDK to execute a managed service, including preparing input data, running the service, and retrieving results.

```python
from qhub.service.client import HubServiceClient

# Create a client instance
client = HubServiceClient(
    "https://<your_service_endpoint_url>",
    "your_access_key_id",
    "your_secret_access_key"
)

# Prepare your input data and parameters
data = {"values": [1, 2, 3, 4, 5]}
params = {"algorithm": "quantum_fourier_transform", "shots": 1000}

# Start a service execution
execution = client.run(request={"data": data, "params": params})

# Wait for completion and get results
execution.wait_for_final_state()
result = execution.result()

print(f"Execution finished with status: {execution.status}")
print(f"Result: {result}")
```

--------------------------------

### Install Kipu Quantum SDK

Source: https://docs.hub.kipu-quantum.com/sdk-reference.html

Installs the required Python package for the Kipu Quantum SDK using pip. Ensure you are using a clean virtual environment with Python 3.11 or higher.

```bash
pip install --upgrade qhub-quantum
```

--------------------------------

### Using the SDK - User Context

Source: https://docs.hub.kipu-quantum.com/sdk-api-reference.html

Example of how to create a `HubPlatformClient` instance for user context authentication.

```APIDOC
## Using the SDK

### Use With User Context

Create a `HubPlatformClient` instance to interact with the API:

```python
from qhub.api.platform.client import HubPlatformClient

# Create a client (authenticates via environment variable)
client = HubPlatformClient()

# Or, pass the token directly
# client = HubPlatformClient(access_token="YOUR_PERSONAL_ACCESS_TOKEN")
```
```

--------------------------------

### Get Help for Kipu Quantum Hub CLI Commands

Source: https://docs.hub.kipu-quantum.com/cli-reference.html

Provides general help for all supported commands or specific help for a single command.

```bash
qhubctl help

qhubctl help <command>

qhubctl <command> --help
```

--------------------------------

### Setup Python Environment for Quantum Services

Source: https://docs.hub.kipu-quantum.com/tutorials/tutorial-ibmq.html

Commands to create and activate a Conda environment for the project, and to execute the service module from the console.

```bash
conda env create -f environment.yml
conda activate <environment name>
python3 -m src
```

--------------------------------

### Using the SDK - Organization Context

Source: https://docs.hub.kipu-quantum.com/sdk-api-reference.html

Example of how to create a `HubPlatformClient` instance for organization context authentication.

```APIDOC
### Use With Organization Context

Create a `HubPlatformClient` instance to interact with the API in the context of an organization:

```python
from qhub.api.client import HubPlatformClient

# Create a client for an organization (authenticates via environment variable)
client = HubPlatformClient(organization_id="YOUR_ORGANIZATION_ID")

# Or, pass the token directly
# client = HubPlatformClient(organization_id="YOUR_ORGANIZATION_ID", access_token="YOUR_PERSONAL_ACCESS_TOKEN")
```
```

--------------------------------

### GET /backends

Source: https://docs.hub.kipu-quantum.com/sdk-quantum-client-reference.html

Retrieves a list of all available quantum backends and their basic information.

```APIDOC
## GET /backends

### Description
List all available quantum backends accessible to the authenticated user.

### Method
GET

### Endpoint
/backends

### Parameters
None

### Response
#### Success Response (200)
- **backends** (array) - A list of backend objects containing id and name.

#### Response Example
{
  "backends": [
    {"id": "aws.ionq.aria", "name": "IonQ Aria"},
    {"id": "azure.ionq.simulator", "name": "IonQ Simulator"}
  ]
}
```

--------------------------------

### Docker container input file mounting example

Source: https://docs.hub.kipu-quantum.com/services/managed/openapi.html

Demonstrates how input data and parameters are mounted as files within a custom Docker container at runtime. The platform creates `data.json` and `params.json` in `/var/runtime/input`.

```bash
# Example: data.json mounted at /var/runtime/input/data.json
# Example: params.json mounted at /var/runtime/input/params.json
```

--------------------------------

### Define Workflow Input Parameters

Source: https://docs.hub.kipu-quantum.com/services/workflow/air-traffic-tutorial.html

Example JSON schema for defining input parameters at the Start Event. These parameters become accessible as workflow variables throughout the process.

```json
{
  "flightRoutes": [
    {
      "origin": "HEL",
      "destination": "FCO"
    }
  ],
  "mapOutput": {
     "ref": "datapool",
     "id": "uuid-of-your-datapool"
  }
}
```

--------------------------------

### Initialize and Add Service SDK with uv

Source: https://docs.hub.kipu-quantum.com/sdk-reference-service.html

Demonstrates initializing a new Python project with uv, adding the Service SDK (qhub-service), and running a Python script.

```bash
# Create a new project directory
mkdir my-project
cd my-project

# Initialize a new Python project
uv init

# Add the Service SDK
uv add qhub-service

# Run your Python script
uv run python your_script.py
```

--------------------------------

### Example API Result Response

Source: https://docs.hub.kipu-quantum.com/services/managed/openapi.html

A sample JSON response returned by the GET /{id}/result endpoint. It demonstrates the inclusion of result data, embedded execution status, and HATEOAS links for further resources.

```json
{
  "sum": 6,
  "_embedded": {
    "status": {
      "id": "ee49be82-593d-4d12-b732-ab84e0b11be1",
      "createdAt": "2025-03-14 14:09:33",
      "startedAt": "2025-03-14 14:10:45",
      "endedAt": "2025-03-14 14:11:00",
      "status": "SUCCEEDED"
    }
  },
  "_links": {
    "self": {
      "href": "...service endpoint.../ee49be82-593d-4d12-b732-ab84e0b11be1/result"
    },
    "status": {
      "href": "...service endpoint.../ee49be82-593d-4d12-b732-ab84e0b11be1"
    },
    "hello.jpg": {
      "href": "...service endpoint.../ee49be82-593d-4d12-b732-ab84e0b11be1/result/hello.jpg"
    },
    "output.json": {
      "href": "...service endpoint.../ee49be82-593d-4d12-b732-ab84e0b11be1/result/output.json"
    }
  }
}
```

--------------------------------

### Install and Verify uv Package Manager

Source: https://docs.hub.kipu-quantum.com/tutorials/tutorial-datapool.html

Installs the uv package manager for Python dependency management. Includes instructions for macOS/Linux and Windows, and verifies the installation.

```bash
# On macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows:
# powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Verify uv installation
uv --version
```

--------------------------------

### Initialize a New Service Project with CLI

Source: https://docs.hub.kipu-quantum.com/cli-reference.html

Bootstraps a new project to create a service. Can be run interactively or non-interactively.

```bash
qhubctl init [--name ...] [--non-interactive]
```

--------------------------------

### Install uv Package Manager

Source: https://docs.hub.kipu-quantum.com/sdk-reference-service.html

Installs the uv package and project manager, a fast alternative to pip for Python. Supports installation via curl, PowerShell, or pip.

```bash
# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or using pip
pip install uv
```

--------------------------------

### Project Initialization

Source: https://docs.hub.kipu-quantum.com/cli-reference.html

Commands for bootstrapping new projects and services.

```APIDOC
## Initialize Project

### Description
Bootstraps a new project directory to create a service.

### Method
CLI Command

### Endpoint
qhubctl init

### Parameters
#### Options
- **--name** (string) - Optional - The name of the service
- **--non-interactive** (boolean) - Optional - Run in non-interactive mode

### Request Example
qhubctl init --name my-quantum-service
```

--------------------------------

### Serve Project Locally with CLI

Source: https://docs.hub.kipu-quantum.com/cli-reference.html

Runs your project locally using qhub-serve, exposing the same HTTP endpoints as the Kipu Quantum Hub for local testing.

```bash
qhubctl serve
```

--------------------------------

### Example JSON Schema for Flight Routes

Source: https://docs.hub.kipu-quantum.com/services/workflow/api-generation.html

A practical example of a JSON Schema used for a workflow that processes flight routes, including definitions for flight routes and map output.

```APIDOC
### Example Schema 

Here's a simple example for a workflow that processes flight routes:

```json
{
  "type": "object",
  "properties": {
    "flightRoutes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "origin": { "type": "string" },
          "destination": { "type": "string" }
        },
        "required": ["origin", "destination"]
      }
    },
    "mapOutput": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "ref": {
          "type": "string",
          "enum": ["datapool"]
        }
      },
      "required": ["id", "ref"],
      "additionalProperties": false
    }
  },
  "required": ["flightRoutes", "mapOutput"]
}
```

This schema defines:
  * **flightRoutes** : An array of route objects, each with origin and destination (both required)
  * **mapOutput** : An object with datapool reference information (id and ref both required)
  * Both top-level properties are marked as required
```

--------------------------------

### Set Up Local Development Environment

Source: https://docs.hub.kipu-quantum.com/quickstart.html

These bash commands set up a local Python development environment for a Kipu Quantum Hub project. They involve navigating to the project directory, creating a virtual environment using `uv`, syncing dependencies, and activating the environment.

```bash
cd my-project
uv venv
uv sync

source .venv/bin/activate
```

--------------------------------

### Set Up Python Environment with uv

Source: https://docs.hub.kipu-quantum.com/tutorials/tutorial-datapool.html

Initializes a Python project environment using the uv package manager within the service project directory. It synchronizes dependencies and optionally activates the virtual environment.

```bash
# Initialize a Python project with uv in the current directory
uv sync -U

# Activate the environment (optional, uv will handle this automatically)
source .venv/bin/activate  # On Windows: .venv\Scripts\activate.[ps1|bat]
```

--------------------------------

### Initialize a Docker Python Project

Source: https://docs.hub.kipu-quantum.com/implementations/create-a-service.html

Initializes a new quantum service project using the CLI interactive prompt. This command sets up the directory structure based on the Docker Python Starter template.

```bash
qhubctl init
```

--------------------------------

### Example: Reporting Usage with cURL

Source: https://docs.hub.kipu-quantum.com/services/on-premise/report-usage.html

Demonstrates how to report service usage to the Metering API using a cURL command. This example shows the necessary headers, including the authentication token, and the JSON payload with sample data.

```shell
curl -X 'POST' 'https://api.hub.kipu-quantum.com/qc-catalog/external-services/metering' \
  -H 'Accept: */*' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-Token: <your access token>' \
  -d '{
    "correlationId": "bXlleHRlcm5hbHNlcnZpY2VuYW1lOnRoZWFwcGxpY2F0aW9ubmFtZXRoYXRpc3N1YnNjcmliZWQ=",
    "productId": "prod_YX8skS2X",
    "count": 10
}'
```

--------------------------------

### GET /

Source: https://docs.hub.kipu-quantum.com/files/openapi/openapi-service.yaml

Retrieves a list of all service executions.

```APIDOC
## GET /

### Description
Retrieves a list of all service executions. The response includes links to each service execution, allowing for further queries on their status and results.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- **executions** (array) - List of service execution objects.

#### Response Example
[
  { "id": "exec-123", "status": "SUCCEEDED" }
]
```

--------------------------------

### Initialize Text Analyzer Service Project

Source: https://docs.hub.kipu-quantum.com/tutorials/tutorial-datapool.html

Creates a new service project named 'text-analyzer' using the Quantum Hub CLI and navigates into the project directory. This sets up the basic project structure including source files, input directories, and configuration files.

```bash
qhubctl init --name text-analyzer
cd text-analyzer
```

--------------------------------

### Example API Response for Workflow Outputs

Source: https://docs.hub.kipu-quantum.com/services/workflow/air-traffic-tutorial.html

An example JSON structure representing the API response from a quantum air traffic optimization workflow. It includes configured output variables like 'corridors', 'quantum_result', and 'status', showcasing how optimization results are returned programmatically.

```JSON
{
  "corridors": [
    {
      "channel": "Corridor 0",
      "routes": [
        {
          "origin": "HEL",
          "destination": "FCO"
        }
      ]
    },
    {
      "channel": "Corridor 1",
      "routes": [
        {
          "origin": "BER",
          "destination": "MAD"
        }
      ]
    }
  ],
  "quantum_result": [
    1,
    0,
    1,
    0,
    1
  ],
  "status": "optimization_complete"
}
```

--------------------------------

### GET /{id}/result

Source: https://docs.hub.kipu-quantum.com/files/openapi/openapi-service.yaml

Retrieves the result of a service execution.

```APIDOC
## GET /{id}/result

### Description
Retrieves the result of a service execution. The result is returned as a JSON object containing the status and any additional data.

### Method
GET

### Endpoint
/{id}/result

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the service execution.

### Response
#### Success Response (200)
- **result** (object) - The execution result data.

#### Response Example
{ "status": "SUCCEEDED", "data": { "value": 0.98 } }
```

--------------------------------

### Create and Execute a Quantum Circuit

Source: https://docs.hub.kipu-quantum.com/sdk-reference.html

Demonstrates how to initialize a QuantumCircuit, apply gates, and execute it on a backend using the Kipu Quantum Hub interface.

```python
circuit = QuantumCircuit(2, 2)
circuit.h(0)
circuit.cx(0, 1)
circuit.measure(range(2), range(2))
job = backend.run(circuit, shots=10)
```

--------------------------------

### GET /{id}

Source: https://docs.hub.kipu-quantum.com/files/openapi/openapi-service.yaml

Retrieves the status of a specific service execution.

```APIDOC
## GET /{id}

### Description
Retrieves the status of a service execution. The status can be one of the following: UNKNOWN, PENDING, RUNNING, SUCCEEDED, CANCELLED, FAILED.

### Method
GET

### Endpoint
/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the service execution.

### Response
#### Success Response (200)
- **status** (string) - The current status of the execution.

#### Response Example
{ "id": "exec-456", "status": "RUNNING" }
```

--------------------------------

### GET /{id}/log

Source: https://docs.hub.kipu-quantum.com/services/managed/openapi.html

Retrieves the execution logs for a specific service run.

```APIDOC
## GET /{id}/log

### Description
Retrieves the complete log output generated by the service execution, provided line by line.

### Method
GET

### Endpoint
/{id}/log

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the service execution.
```

--------------------------------

### Initialize HubPlatformClient for User Context (Python)

Source: https://docs.hub.kipu-quantum.com/sdk-api-reference.html

Demonstrates how to create an instance of the HubPlatformClient for user context authentication. It shows authentication via environment variable or directly passing an access token.

```python
from qhub.api.platform.client import HubPlatformClient

# Create a client (authenticates via environment variable)
client = HubPlatformClient()

# Or, pass the token directly
# client = HubPlatformClient(access_token="YOUR_PERSONAL_ACCESS_TOKEN")
```

--------------------------------

### Initialize HubQiskitProvider

Source: https://docs.hub.kipu-quantum.com/sdk-reference.html

Demonstrates how to import and instantiate the HubQiskitProvider. It supports automatic authentication via CLI login or explicit token and organization ID configuration.

```python
from qhub.quantum.sdk import HubQiskitProvider

# Initialize with CLI credentials
provider = HubQiskitProvider()

# Initialize with explicit token
provider = HubQiskitProvider(access_token="YOUR_PERSONAL_ACCESS_TOKEN_HERE")

# Initialize with organization context
provider = HubQiskitProvider(organization_id="YOUR_ORGANIZATION_ID_HERE", access_token="...")
```

--------------------------------

### GET /execution/{id}

Source: https://docs.hub.kipu-quantum.com/services/using-a-service.html

Queries the current status of an asynchronous service execution.

```APIDOC
## GET /{id}

### Description
Retrieves the current state of a specific service execution to check if it is still running or completed.

### Method
GET

### Endpoint
https://gateway.hub.kipu-quantum.com/{subscription_id}/{service_name}/{version}/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique execution ID returned from the POST request.

### Response
#### Success Response (200)
- **status** (string) - Current status (e.g., RUNNING, PENDING, SUCCEEDED, FAILED, UNKNOWN).
```

--------------------------------

### GET /execution/{id}

Source: https://docs.hub.kipu-quantum.com/sdk-reference-service.html

Retrieves the status and results of a specific service execution.

```APIDOC
## GET /execution/{id}

### Description
Monitors the progress of a previously submitted job and retrieves the final result once completed.

### Method
GET

### Endpoint
/execution/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique execution ID returned from the submission.

### Response
#### Success Response (200)
- **status** (string) - The current state (e.g., 'completed', 'failed', 'running').
- **result** (object) - The output data generated by the service.

#### Response Example
{
  "status": "completed",
  "result": {"output": [0.1, 0.5, 0.9]}
}
```

--------------------------------

### POST /run

Source: https://docs.hub.kipu-quantum.com/sdk-reference-service.html

Initiates a new service execution within the Kipu Quantum Hub.

```APIDOC
## POST /run

### Description
Starts a new service execution with the provided request data and returns a ServiceExecution object.

### Method
POST

### Endpoint
/run

### Parameters
#### Request Body
- **request** (Dict) - Required - The data and parameters required to initiate the service execution.

### Request Example
{
  "data": { "key": "value" },
  "params": { "mode": "quantum" }
}

### Response
#### Success Response (200)
- **execution** (ServiceExecution) - The object representing the initiated service execution.

#### Response Example
{
  "id": "exec-123",
  "status": "PENDING",
  "created_at": "2023-10-27T10:00:00Z"
}
```

--------------------------------

### Initialize Aquila Backend

Source: https://docs.hub.kipu-quantum.com/tutorials/tutorial-quera-mis.html

Authenticates the user using a personal access token and retrieves the Aquila device instance from the provider.

```python
provider = HubBraketProvider(access_token="your-access-token", organization_id="my-org-id")
backend = provider.get_device("aws.quera.aquila")
```

--------------------------------

### GET /{id}/result

Source: https://docs.hub.kipu-quantum.com/quickstart.html

Retrieves the final computational results of a completed service execution.

```APIDOC
## GET /{id}/result

### Description
Fetches the final output data and metadata for a successfully completed quantum service execution.

### Method
GET

### Endpoint
/{id}/result

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique ID of the service execution.

### Response
#### Success Response (200)
- **counts** (object) - The quantum measurement results.
- **elapsed_time** (float) - The time taken for execution in seconds.

#### Response Example
{
  "counts": {
    "10": 30,
    "11": 25,
    "00": 24,
    "01": 21
  },
  "elapsed_time": 11.129
}
```

--------------------------------

### Data Pools - Get

Source: https://docs.hub.kipu-quantum.com/sdk-api-reference.html

Retrieve details of a specific data pool by its unique identifier.

```APIDOC
#### Get a Specific Data Pool

Retrieve a data pool by its ID:

```python
data_pool_id = "YOUR_DATA_POOL_ID"
data_pool = client.data_pools.get_data_pool(id=data_pool_id)
print(f"Data Pool Name: {data_pool.name}")
```
```

--------------------------------

### Select and Run Quantum Backend

Source: https://docs.hub.kipu-quantum.com/quickstart.html

This Python snippet demonstrates how to select a quantum backend, transpile a quantum circuit for that backend, and execute the circuit. It retrieves the results, specifically the counts of each outcome.

```python
backend = provider.get_backend("azure.ionq.simulator")

# Transpile the circuit ...
circuit = transpile(circuit, backend)
# ... and run it on the backend
job = backend.run(circuit, shots=100)

counts = job.result().get_counts()

print(counts)
```

--------------------------------

### GET /{id}/result/{file}

Source: https://docs.hub.kipu-quantum.com/services/managed/openapi.html

Downloads specific file artifacts generated by the service execution.

```APIDOC
## GET /{id}/result/{file}

### Description
Downloads a specific file written to the /var/runtime/output directory during service execution.

### Method
GET

### Endpoint
/{id}/result/{file}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the service execution.
- **file** (string) - Required - The name of the file to download (e.g., output.json).
```

--------------------------------

### GET /{id}/result

Source: https://docs.hub.kipu-quantum.com/services/managed/openapi.html

Retrieves the structured result of a service execution as defined by the ResultResponse schema.

```APIDOC
## GET /{id}/result

### Description
Returns the JSON-serializable output of the service execution's run() method, including metadata and links to additional file outputs.

### Method
GET

### Endpoint
/{id}/result

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the service execution.

### Response
#### Success Response (200)
- **ResultResponse** (object) - The structured result object containing execution data, _links, and _embedded status.

#### Response Example
{
  "sum": 6,
  "_embedded": {
    "status": {
      "id": "ee49be82-593d-4d12-b732-ab84e0b11be1",
      "status": "SUCCEEDED"
    }
  },
  "_links": {
    "self": { "href": "/ee49be82-593d-4d12-b732-ab84e0b11be1/result" },
    "output.json": { "href": "/ee49be82-593d-4d12-b732-ab84e0b11be1/result/output.json" }
  }
}
```

--------------------------------

### POST /

Source: https://docs.hub.kipu-quantum.com/quickstart.html

Triggers a new service execution for the quantum project.

```APIDOC
## POST /

### Description
Initiates a new quantum service execution based on the provided input parameters.

### Method
POST

### Endpoint
/

### Request Body
- **data** (object) - Required - The input payload for the quantum service, containing parameters like n_coin_tosses.

### Request Example
{
  "data": {
    "n_coin_tosses": 2
  }
}

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the service execution.

#### Response Example
{
  "id": "5b25134c-dd05-47a0-9c12-ff9816074936"
}
```

--------------------------------

### Execute Qiskit Circuit on a Backend

Source: https://docs.hub.kipu-quantum.com/sdk-reference.html

Selects a Qiskit backend (e.g., a simulator) using the provider and prepares it for circuit execution. This is a prerequisite for running gate-based quantum circuits via Qiskit. Requires the qiskit library.

```python
# Select a certain backend
backend = provider.get_backend("azure.ionq.simulator")
```

--------------------------------

### GET /executions/{id}

Source: https://docs.hub.kipu-quantum.com/sdk-reference-service.html

Retrieves the status and details of a specific service execution by its unique identifier.

```APIDOC
## GET /executions/{id}

### Description
Fetches the current state and metadata for a specific service execution.

### Method
GET

### Endpoint
/executions/{id}

### Parameters
#### Path Parameters
- **id** (str) - Required - The unique identifier of the execution.

### Response
#### Success Response (200)
- **id** (str) - Unique identifier
- **status** (str) - Current status (e.g., RUNNING, SUCCEEDED)
- **created_at** (str) - Creation timestamp

#### Response Example
{
  "id": "exec-123",
  "status": "RUNNING",
  "created_at": "2023-10-27T10:00:00Z"
}
```

--------------------------------

### Submit Quantum Job

Source: https://docs.hub.kipu-quantum.com/sdk-quantum-client-reference.html

Demonstrates submitting a quantum job using the Quantum Client SDK with the IonQ native gate format. This example shows how to define a circuit, specify job parameters, and submit it to a simulator. Note that the client does not perform transpilation; input must match backend capabilities.

```python
from qhub.api.quantum import AzureIonqJobInput

# Define a quantum circuit using IonQ format
ionq_input = AzureIonqJobInput(
    gateset="qis",
    qubits=2,
    circuit=[
        {"gate": "h", "targets": [0]},
        {"gate": "x", "targets": [1], "controls": [0]},
    ]
)

# Submit job to a simulator
job = client.jobs.create_job(
    backend_id="azure.ionq.simulator",
    name="My Quantum Job",
    shots=100,
    input=ionq_input,
    input_params={},
    input_format="IONQ_CIRCUIT_V1"
)

print(f"Job submitted with ID: {job.id}")
print(f"Initial status: {job.status}")
```

--------------------------------

### GET /execution/{id}/result

Source: https://docs.hub.kipu-quantum.com/services/using-a-service.html

Retrieves the final result or error details of a completed service execution.

```APIDOC
## GET /{id}/result

### Description
Fetches the final output data or error information once the service execution status is SUCCEEDED or FAILED.

### Method
GET

### Endpoint
https://gateway.hub.kipu-quantum.com/{subscription_id}/{service_name}/{version}/{id}/result

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique execution ID.
```