Runtime API

The Runtime API is designed as the generic integration surface for applications, SDKs, CLIs and MCP tools.

Capabilities

curl "$QCOS_API_URL/api/v1/runtime/capabilities" \
  -H "Authorization: Bearer $QCOS_API_KEY"

List backends

curl "$QCOS_API_URL/api/v1/runtime/backends" \
  -H "Authorization: Bearer $QCOS_API_KEY"

Estimate cost

curl -X POST "$QCOS_API_URL/api/v1/runtime/estimate" \
  -H "Authorization: Bearer $QCOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "backend_id": "simulator_aer",
    "shots": 4096,
    "qubits": 8,
    "gates": 120,
    "algorithm": "qaoa"
  }'

Submit a dry-run job

curl -X POST "$QCOS_API_URL/api/v1/runtime/jobs?dry_run=true" \
  -H "Authorization: Bearer $QCOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "backend_id": "simulator_aer",
    "qasm": "OPENQASM 2.0; qreg q[2]; creg c[2]; measure q -> c;",
    "shots": 1024,
    "metadata": { "source": "docs" }
  }'

Submit, poll, approve, artifacts

The full job lifecycle on the runtime door:

# Submit (202 Accepted → job_id, status, estimated_cost_usd, cost_basis,
#         credits_required, approval_required, approval_token, created_at)
curl -X POST "$QCOS_API_URL/api/v1/runtime/jobs" \
  -H "Authorization: Bearer $QCOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"backend_id": "simulator_aer", "qasm": "OPENQASM 2.0; ...", "shots": 1024}'

# Fire-and-forget variant
curl -X POST "$QCOS_API_URL/api/v1/runtime/jobs/async" ...

# Poll (result appears in the `result` field when completed)
curl "$QCOS_API_URL/api/v1/runtime/jobs/{job_id}" \
  -H "Authorization: Bearer $QCOS_API_KEY"

# Approve a priced / real-QPU / QEC job
curl -X POST "$QCOS_API_URL/api/v1/runtime/jobs/{job_id}/approve?approval_token=..." \
  -H "Authorization: Bearer $QCOS_API_KEY"

# Cancel
curl -X DELETE "$QCOS_API_URL/api/v1/runtime/jobs/{job_id}" \
  -H "Authorization: Bearer $QCOS_API_KEY"

# Artifacts, including the sealed execution_evidence.json
curl "$QCOS_API_URL/api/v1/runtime/jobs/{job_id}/artifacts" \
  -H "Authorization: Bearer $QCOS_API_KEY"

Provider connections

Use provider connections to register tenant-owned provider credentials.

curl -X POST "$QCOS_API_URL/api/v1/runtime/provider-connections" \
  -H "Authorization: Bearer $QCOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_type": "ibm_quantum",
    "auth_type": "api_key",
    "scope": "workspace",
    "name": "IBM production workspace"
  }'

​Runtime API

​Capabilities

​List backends

​Estimate cost

​Submit a dry-run job

​Submit, poll, approve, artifacts

​Provider connections