---
title: REST API reference
summary: All endpoints of the service, generated from its OpenAPI description. The live, interactive version is served by every deployment at /api/docs.
section: reference
order: 3
level: 2
keywords: [REST, API, endpoints, OpenAPI]
---
<!-- gyre docs: expanded Markdown of reference/rest-api.md (generated tables, verification numbers and chart data are written out). Base level of this page: L2 Practice; passages at another level are bracketed by 'begin level N' / 'end level N' comments and start with [LN Name]. Built from revision ceb1f4b0be. -->

The [Service API guide](../guide/service.md) 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). |