DevelopersHiQ / Use it

API and CLI

HiQ programs are checked, synthesised, compiled and published through the QCOS API. The softqcos command line calls the same routes. This page lists each one and what production answers for it today.

Authentication

Each route takes an API key from your workspace on the Softquantus Research Platform in the X-API-Key header. The CLI reads the key from QCOS_API_KEY. The base URL is https://api.softquantus.com.

Routes

POST/api/v1/runtime/lang/check
Live today
Takes
source, language (qcos/0 by default), include_ir
Returns
ok, diagnostics with line and column, capabilities, target_requirements, declared_qubits, peak_qubits, expanded_ops, gate_counts, depth, subroutines, and ir when asked
POST/api/v1/runtime/lang/synthesize
Live today
Takes
source (C), entry, strategy (scoped, bennett or per_output), include_ir
Returns
ok, diagnostics, qcos_source, report, parameters, result, proof, and ir when asked. Nothing runs
POST/api/v1/runtime/compile/program
Live today
Takes
program (the ir document as JSON text), targets, optimization_level 0 to 3, include_artifact
Returns
One result per target. A target that cannot take the program is refused by name. Nothing runs
POST/api/v1/runtime/programs
Live today
Takes
name, language, source, backend_id, shots, max_shot_budget
Returns
Publishes a checked program in this workspace; 422 with diagnostics on errors. Nothing runs
GET/api/v1/runtime/programs
Live today
Takes
none (also GET and DELETE /programs/{id})
Returns
This workspace's published programs; another workspace's id is 404
POST/api/v1/runtime/run/program
Not open yet
Takes
program, backend_id, shots, max_shot_budget
Returns
The result of a run on a Softquantus Cloud simulator, and its evidence
POST/api/v1/runtime/programs/{id}/invoke
Not open yet
Takes
reservation_ref (optional)
Returns
Runs exactly what was published, through every gate of run/program

Command line

Install the client with pip install softqcos. Every command below is a subcommand of softqcos lang.

softqcos lang check FILE [--json]Live today
Check a program. Exits 1 when it has errors. Nothing compiles or runs.
softqcos lang synthesize FILE.c [--entry NAME] [--strategy scoped|bennett|per_output] [-o OUT.qcos]Live today
Turn one C function into a reversible oracle. Exits 1 when it is refused.
softqcos lang compile FILE --target ID [--target ID] [-O 0-3] [--artifact]Live today
Check a program, then compile it for hardware profiles. Nothing runs.
softqcos lang publish FILE --name NAME --backend ID --shots N --max-shot-budget NLive today
Publish a program so any key of this workspace can find it by id. Nothing runs.
softqcos lang programsLive today
List this workspace's published programs.
softqcos lang run FILE --backend ID --shots N --max-shot-budget NNot open yet
Check a program, then run it on a Softquantus Cloud simulator. Refused in production today.
softqcos lang invoke IDNot open yet
Run a published program. Refused in production today.

A first request

The same check as the quickstart, sent directly to the API:

Terminal

curl -X POST https://api.softquantus.com/api/v1/runtime/lang/check \
  -H "X-API-Key: $QCOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"language": "qcos/0", "source": "program bell\nqubits a, b\nbits m0, m1\nh a\ncx a, b\nmeasure a -> m0\nmeasure b -> m1"}'

The answer has ok, the diagnostics with line and column, and the counts: declared_qubits, peak_qubits, expanded_ops, depth and gate_counts. Add "include_ir": true to get the qcos-ir/2 document that compile/program takes.