Endpoints¶

All endpoints are prefixed with /api/v1/

Programs¶

Manage quantum programs (functions).

List Programs¶

GET /programs/

List all accessible programs.

Query Parameters:

filter (optional) - Filter by type: serverless or catalog

Response:

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "my-function",
    "entrypoint": "main.py",
    "dependencies": ["qiskit==1.0.0"],
    "provider": null,
    "type": "GENERIC",
    "version": "1.0.0"
  }
]

Get Program by Title¶

GET /programs/get_by_title/{title}/

Retrieve a program by its title.

Query Parameters:

provider (optional) - Provider name if program is provider-owned

Upload Program¶

POST /programs/upload/

Upload a new program.

Request Body: Multipart form data

title (required) - Program title
entrypoint (required) - Entry point file
artifact (required) - Program artifact (.tar file)
dependencies (optional) - List of dependencies
description (optional) - Program description

Run Program¶

POST /programs/run/

Execute a program and create a job.

Request Body:

{
  "title": "my-function",
  "arguments": {
    "param1": "value1"
  },
  "config": {
    "workers": 2,
    "auto_scaling": true
  }
}

Response:

{
  "id": "987fcdeb-51a2-43f1-b789-123456789abc",
  "status": "QUEUED"
}

Jobs¶

Manage job execution and monitoring.

List Jobs¶

GET /jobs/

List jobs with optional filtering.

Query Parameters:

function (optional) - Filter by function title
provider (optional) - Filter by provider
status (optional) - Filter by job status
filter (optional) - Type: catalog or serverless
limit (optional) - Results per page (default: 10)
offset (optional) - Number of results to skip (default: 0)
created_after (optional) - ISO 8601 datetime filter

Response:

{
  "count": 42,
  "next": "https://qiskit-serverless.quantum.ibm.com/api/v1/jobs/?limit=10&offset=10",
  "previous": null,
  "results": [
    {
      "id": "987fcdeb-51a2-43f1-b789-123456789abc",
      "status": "SUCCEEDED",
      "program": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "title": "my-function"
      },
      "created": "2024-01-15T10:30:00Z"
    }
  ]
}

Get Job¶

GET /jobs/{job_id}/

Retrieve a specific job by ID.

Query Parameters:

with_result (optional) - Include result field (default: true)

Response:

{
  "id": "987fcdeb-51a2-43f1-b789-123456789abc",
  "status": "SUCCEEDED",
  "result": {
    "counts": {"00": 512, "11": 512}
  },
  "program": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "my-function"
  },
  "created": "2024-01-15T10:30:00Z"
}

Get Job Logs¶

GET /jobs/{job_id}/logs/

Retrieve execution logs for a job.

Response:

{
  "logs": "Job started...\nExecuting quantum circuit...\nJob completed."
}

Stop Job¶

POST /jobs/{job_id}/stop/

Stop a running job.

Request Body:

{
  "service": "ray"
}

Response:

{
  "message": "Job stopped successfully"
}

Files¶

Manage files associated with programs.

Upload File¶

POST /files/upload/

Upload a file to user storage.

Query Parameters:

function (required) - Function title
provider (optional) - Provider name

Request Body: Multipart form data with file field

Download File¶

GET /files/download/

Download a file from user storage.

Query Parameters:

function (required) - Function title
file (required) - File name
provider (optional) - Provider name

List Files¶

GET /files/list/

List files in user storage.

Query Parameters:

function (required) - Function title
provider (optional) - Provider name

Response:

{
  "files": ["data.txt", "results.json"]
}

Delete File¶

DELETE /files/delete/

Delete a file from user storage.

Query Parameters:

function (required) - Function title
file (required) - File name
provider (optional) - Provider name

System¶

Health checks and system information.

Version¶

GET /version/

Get Gateway version information.

Authentication: Not required

Response:

{
  "version": "0.30.0"
}

Readiness Probe¶

GET /readiness/

Check if the Gateway is ready to accept requests.

Authentication: Not required

Liveness Probe¶

GET /liveness/

Check if the Gateway is alive.

Authentication: Not required

Job Status Values¶

QUEUED - Job created, waiting for scheduling
PENDING - Submitted to Ray, waiting to start
RUNNING - Currently executing
SUCCEEDED - Completed successfully
FAILED - Execution failed
STOPPED - Manually stopped by user