REST API reference
In one minuteAll endpoints of the service, generated from its OpenAPI description. The live, interactive version is served by every deployment at /api/docs.
The Service API guide explains usage; this page lists every route.
Meta#
| method | path | description |
|---|---|---|
GET |
/api/v1/health |
Liveness probe; never needs a token. |
GET |
/api/v1/info |
Identity of this deployment: version, source revision, process id, device, uptime, operator limits and allowed host names; never needs a token. |
GET |
/api/v1/metrics |
Prometheus text exposition: build, uptime, job, session and pipeline counters. |
Cases#
| method | path | description |
|---|---|---|
GET |
/api/v1/presets |
Built-in cases: name, description and size estimate of each. |
GET |
/api/v1/presets/{name} |
The complete CaseSpec of a preset (404 UnknownPreset). |
GET |
/api/v1/schema/case |
JSON Schema of a case specification (CaseSpec). |
GET |
/api/v1/schema/job |
JSON Schema of a job request (the body of POST /jobs). |
POST |
/api/v1/cases/validate |
Dry run: resolve a case, report its size, where it would execute and its names. |
Meshes#
| method | path | description |
|---|---|---|
GET |
/api/v1/meshes |
Meshes of the mesh store under meshes, each with its summary (see GET /meshes/{name}). |
PUT |
/api/v1/meshes/{name} |
Store a mesh file (Gmsh .msh 2.2 / 4.1 ASCII, or Gyre .npz) under name. |
GET |
/api/v1/meshes/{name} |
Summary of a stored mesh: name, bytes, sha256, dim, elements, geometry_order, nodes, boundaries, bounding_box, quality numbers. 404 UnknownMesh; 422 InvalidMesh for a file of the store’s directory that is not a usable mesh (placed there by hand). |
DELETE |
/api/v1/meshes/{name} |
Remove a mesh from the store. Jobs that were queued on it will fail; finished results and open sessions are unaffected (a session has read its mesh when it started). 404 UnknownMesh. |
Jobs#
| method | path | description |
|---|---|---|
POST |
/api/v1/jobs |
Queue a batch analysis; returns immediately with the job record. |
GET |
/api/v1/jobs |
Jobs, newest first; state filters (queued, running, succeeded, failed, cancelled, interrupted). |
GET |
/api/v1/jobs/{job_id} |
Job record; wait long-polls up to that many seconds for completion. |
DELETE |
/api/v1/jobs/{job_id} |
Cancel a queued or running job (its worker process is terminated); returns the job record. A job that has already ended is returned unchanged. |
GET |
/api/v1/jobs/{job_id}/result |
Result of a finished job: outputs, history, provenance and, if requested, gradients, error estimates and the order selection. 409 NotReady before the job has succeeded. |
GET |
/api/v1/jobs/{job_id}/events |
Progress events; stream=true returns a Server-Sent-Events stream. |
GET |
/api/v1/jobs/{job_id}/artifacts/{name} |
Download a file of a job: result.json, solution.npz (checkpoint), flow.vtu, field.json, events.jsonl, request.json, error.txt (traceback of a failed job). |
Sessions#
| method | path | description |
|---|---|---|
GET |
/api/v1/sessions |
Open sessions with their case, device, call counts and idle time. |
POST |
/api/v1/sessions |
Start a warm solver process for repeated evaluations of one case. |
GET |
/api/v1/sessions/{sid} |
A session: case, device, counters and interface (names, shapes and current values of the inputs; the outputs); commands when the solver process reports the commands of POST /sessions/{id}/{command}. |
DELETE |
/api/v1/sessions/{sid} |
Close a session and end its solver process (its flow state is discarded). |
POST |
/api/v1/sessions/{sid}/evaluate |
Set inputs, converge the flow (warm start) and return outputs. |
POST |
/api/v1/sessions/{sid}/gradients |
Total derivatives of scalar outputs at the current converged state. |
POST |
/api/v1/sessions/{sid}/adjoint |
Reverse total product (d outputs / d inputs)^T seeds (coupled-adjoint block). |
POST |
/api/v1/sessions/{sid}/error-estimate |
Adjoint-based discretization-error estimates of scalar outputs. |
GET |
/api/v1/sessions/{sid}/surface |
Coordinates of the surface nodes that x_surface displaces. |
GET |
/api/v1/sessions/{sid}/distributions |
Wall distributions (cp, cf) of the converged state. 422 RuntimeError before the first evaluation and while the last evaluation did not converge. |
GET |
/api/v1/sessions/{sid}/field |
Flow fields of the converged state for plotting. 422 RuntimeError before the first evaluation and while the last evaluation did not converge. |
GET |
/api/v1/sessions/{sid}/state |
Current inputs, whether a flow state exists (solved), whether the last evaluation converged (converged) and the residual norm of the kept state. |
POST |
/api/v1/sessions/{sid}/{command} |
Run any command of the session’s solver process: the generic pass-through. |
Pipelines#
| method | path | description |
|---|---|---|
GET |
/api/v1/pipelines |
Pipeline definitions of this deployment (name, stages, params with their defaults, parameters: every name a run may set, runnable; reason when a definition cannot be started through the service). |
POST |
/api/v1/pipelines/{name}/runs |
Start a pipeline run; unchanged stages are served from the stage cache. |
GET |
/api/v1/pipelines/runs |
Pipeline runs, newest first. |
GET |
/api/v1/pipelines/runs/{run_id} |
Run status and progress; wait long-polls up to that many seconds for the end. |
DELETE |
/api/v1/pipelines/runs/{run_id} |
Cancel an active pipeline run: its process group (the engine and the stage it is running) is terminated. Returns the run’s status document, cancelled once the processes have ended (the call waits up to wait seconds for that; otherwise cancel_requested is true and the status follows). A run that has already ended is returned unchanged. Stages that completed stay in the stage cache. |
GET |
/api/v1/pipelines/runs/{run_id}/artifacts/{stage} |
Names of the files stage stage of this run left behind (under artifacts). |
GET |
/api/v1/pipelines/runs/{run_id}/artifacts/{stage}/{name} |
Download a file a stage of this run produced: report.md and report.json of a report stage, result.json, solution.npz and flow.vtu of a solve stage, sweep.json, orders.json, stage.log. 404 when the stage did not succeed in this run, the name is not a plain file name, or a later run of the pipeline has replaced the stage’s files (stage directories are shared by the runs of a pipeline). |