Serve API reference¶
Generated
This page is generated from the code when the documentation is built (docs/hooks/reference.py). Do not edit it; change the code instead.
The routes of cheme serve (extra serve), from the OpenAPI document of chemeascode.interfaces.api.serve.create_app; a running server also serves it at /api/openapi.json. What each route returns, the error codes and the security rules are described in Viewer and cheme serve; the "Returns" notes below come from the endpoint table there (REFERENCE.md).
| method | path | summary |
|---|---|---|
| GET | /api/repo |
Get Repo |
| GET | /api/branches |
Get Branches |
| GET | /api/log |
Get Log |
| GET | /api/tree |
Get Tree |
| GET | /api/file |
Get File |
| GET | /api/pid.svg |
Get Pid Svg |
| GET | /api/diff |
Get Diff |
| GET | /api/yaml |
Get Yaml |
| GET | /api/layout |
Get Layout |
| GET | /api/layout/plan.svg |
Get Layout Plan |
| GET | /api/mto |
Get Mto |
| GET | /api/estimate/equipment |
Get Equipment Estimate |
| GET | /api/datasheets |
Get Datasheets |
| GET | /api/datasheets/{tag}.svg |
Get Datasheet Drawing |
| GET | /api/datasheets/{tag} |
Get Datasheet |
| GET | /api/lca |
Get Lca |
| GET | /api/tea |
Get Tea |
| GET | /api/layout/section.svg |
Get Layout Section |
| GET | /api/status |
Get Status |
| GET | /api/impact |
Get Impact |
| GET | /api/interlocks |
Get Interlocks |
| GET | /api/issues |
Get Issues |
| GET | /api/control |
Get Control |
| GET | /api/streams |
Get Streams |
| GET | /api/simulation |
Get Simulation |
| GET | /api/kinetics |
Get Kinetics |
| GET | /api/library |
Get Library |
| GET | /api/reactions |
Get Reactions |
| GET | /api/validate |
Get Validate |
| GET | /api/maturity |
Get Maturity |
| GET | /api/session |
Get Session |
| POST | /api/checks/run |
Post Checks Run |
| GET | /api/checks |
Get Checks |
GET /api/repo¶
Get Repo
Returns: name, root_name, branch, head, stage, stages, sheets (each with kind pid, bfd or pfd), dirty, has_layout, has_lca, has_tea (estimate/tea.yaml), has_equipment_estimate (the equipment list lists items), has_simulation (process/simulation.yaml), has_reactions (process/reactions.yaml), has_kinetic_data (experiments/kinetics/*.yaml)
| parameter | in | type | required | default | description |
|---|---|---|---|---|---|
rev |
query | string or null |
Responses:
200: Successful Response (application/json)422: Validation Error (application/json)
GET /api/branches¶
Get Branches
Returns: [{name, head, current}]
No parameters.
Responses:
200: Successful Response (application/json)
GET /api/log¶
Get Log
Returns: [{sha, short, author, date, subject}]
| parameter | in | type | required | default | description |
|---|---|---|---|---|---|
limit |
query | integer | 50 |
||
path |
query | string or null | |||
rev |
query | string or null |
Responses:
200: Successful Response (application/json)422: Validation Error (application/json)
GET /api/tree¶
Get Tree
Returns: [{path, type, kind}], kind pid, yaml, markdown, json or other
| parameter | in | type | required | default | description |
|---|---|---|---|---|---|
rev |
query | string or null |
Responses:
200: Successful Response (application/json)422: Validation Error (application/json)
GET /api/file¶
Get File
Returns: the file as text (400 for binary or over 5 MB)
| parameter | in | type | required | default | description |
|---|---|---|---|---|---|
path |
query | string | yes | ||
rev |
query | string or null |
Responses:
200: Successful Response (application/json)422: Validation Error (application/json)
GET /api/pid.svg¶
Get Pid Svg
Returns: the sheet rendered, as cheme render draws it
| parameter | in | type | required | default | description |
|---|---|---|---|---|---|
path |
query | string | yes | ||
rev |
query | string or null |
Responses:
200: Successful Response (application/json)422: Validation Error (application/json)
GET /api/diff¶
Get Diff
Returns: changes, both SVGs, highlight maps, old_owner/new_owner (changed id to drawn id), status (added/removed for a sheet on one side), review-text diff
| parameter | in | type | required | default | description |
|---|---|---|---|---|---|
path |
query | string | yes | ||
old |
query | string | "HEAD" |
||
new |
query | string or null |
Responses:
200: Successful Response (application/json)422: Validation Error (application/json)
GET /api/yaml¶
Get Yaml
Returns: {data, kind, schema} for a .yaml/.yml mapping or list; kind is a list or layout kind, plant, materials, flowsheet or null
| parameter | in | type | required | default | description |
|---|---|---|---|---|---|
path |
query | string | yes | ||
rev |
query | string or null |
Responses:
200: Successful Response (application/json)422: Validation Error (application/json)
GET /api/layout¶
Get Layout
Returns: {site, areas, roads, racks, buildings (with footprint), equipment: [{tag, type, service, position, shape, family, size [dx, dy, dz], size_from (list, placement, default), rotation_deg, on, building, level, sheet, sheet_file, bbox, clash, notes}], lines: [{number, from, to, from_point, to_point, distance, length_est, racks, finding}], separations, model, notes, files, rev, findings} with the layout findings; separations as written in the site plan, model the generated layout/plant-model.yaml (null without one; see docs/framework/layout-model.md); 404 without layout files
| parameter | in | type | required | default | description |
|---|---|---|---|---|---|
rev |
query | string or null |
Responses:
200: Successful Response (application/json)422: Validation Error (application/json)
GET /api/layout/plan.svg¶
Get Layout Plan
The plot plan, or a level plan (level= id, or z=a,b), of the committed model at rev.
Returns: the plot plan of the committed layout/plant-model.yaml, or a level plan (level= a structure or building level id, or z=a,b an elevation range); see docs/framework/layout-model.md; 404 without a model or for an unknown level, 400 for a bad z
| parameter | in | type | required | default | description |
|---|---|---|---|---|---|
rev |
query | string or null | |||
level |
query | string or null | |||
z |
query | string or null |
Responses:
200: Successful Response (application/json)422: Validation Error (application/json)
GET /api/mto¶
Get Mto
The material take-off of the committed model at rev (cheme assess mto --json without the source), and its estimate when estimate/rates.yaml exists.
Returns: the material take-off of the committed layout/plant-model.yaml: {rev, model, model_sha256, columns, rows, totals, findings, estimate}, estimate priced with estimate/rates.yaml (null without one); see docs/framework/mto.md; 404 without a model
| parameter | in | type | required | default | description |
|---|---|---|---|---|---|
rev |
query | string or null |
Responses:
200: Successful Response (application/json)422: Validation Error (application/json)
GET /api/estimate/equipment¶
Get Equipment Estimate
The equipment estimate at rev (cheme assess equipment --json): the equipment list costed from the published correlations, with estimate/cost-basis.yaml and the datasheets. 404 without an equipment list or with no items; 422 for a list that does not load.
Returns: the equipment estimate (cheme assess equipment --json): {rev, currency, base, index, estimate_class, accuracy, totals, lines, own_costs, findings, source}; see docs/framework/mto.md; 404 without an equipment list or with no items, 422 for a list that does not load
| parameter | in | type | required | default | description |
|---|---|---|---|---|---|
rev |
query | string or null |
Responses:
200: Successful Response (application/json)422: Validation Error (application/json)
GET /api/datasheets¶
Get Datasheets
The datasheets at rev: per datasheet its tag, class, service, draft, the counts of assumed, TBD, supplier and not_applicable fields, the outline drawing's state and the findings by level; the listed items without a datasheet. 404 without datasheets.
Returns: the equipment datasheets (equipment/datasheets/): {rev, directory, datasheets: [{tag, file, valid, type, service, draft, counts, drawing, drawing_current, findings, ...}], missing, source}; see docs/framework/datasheet-drawings.md; 404 without datasheets
| parameter | in | type | required | default | description |
|---|---|---|---|---|---|
rev |
query | string or null |
Responses:
200: Successful Response (application/json)422: Validation Error (application/json)
GET /api/datasheets/{tag}.svg¶
Get Datasheet Drawing
The outline drawing of tag at rev: the committed equipment/datasheets/<TAG>.svg, or (when there is none, or with generated=true) the one cheme datasheets drawing would write. X-Cheme-Drawing says which (committed or generated), X-Cheme-Drawing-Current whether the committed one is what the datasheet gives now.
Returns: its outline drawing: the committed SVG, or the generated one when none is committed or with generated=true; headers X-Cheme-Drawing (committed or generated) and X-Cheme-Drawing-Current; 422 for a datasheet that does not validate
| parameter | in | type | required | default | description |
|---|---|---|---|---|---|
tag |
path | string | yes | ||
rev |
query | string or null | |||
generated |
query | boolean | false |
Responses:
200: Successful Response (application/json)422: Validation Error (application/json)
GET /api/datasheets/{tag}¶
Get Datasheet
One datasheet at rev: the file as data, the parsed datasheet (None when it does not validate), its summary as in /api/datasheets and the findings on it and its drawing (schema, markers, against the equipment list, the layout model, the P&IDs and the line list, drawing drift).
Returns: one datasheet: {rev, tag, file, summary, datasheet (parsed, null when it does not validate), data, drawing: {file, state, current}, findings, source}; 404 without it
| parameter | in | type | required | default | description |
|---|---|---|---|---|---|
tag |
path | string | yes | ||
rev |
query | string or null |
Responses:
200: Successful Response (application/json)422: Validation Error (application/json)
GET /api/lca¶
Get Lca
The LCA at rev (cheme assess lca --json without the source): inventory, impacts by scenario, category, phase and contributor, and the findings. 404 without lca/lca.yaml; 422 when the LCA does not compute (its first error).
Returns: the LCA (cheme assess lca --json without the source): inventory, impacts by scenario, category, phase and contributor, findings; see docs/framework/lca.md; 404 without lca/lca.yaml or plant.yaml, 422 when it does not compute
| parameter | in | type | required | default | description |
|---|---|---|---|---|---|
rev |
query | string or null |
Responses:
200: Successful Response (application/json)422: Validation Error (application/json)
GET /api/tea¶
Get Tea
The TEA at rev (cheme assess tea --json without the source): premises, capital cost, flows, cash flow, results, scenarios, tornado, break-even values, the Monte Carlo and the findings. 404 without estimate/tea.yaml; 422 when the TEA does not compute (its first error).
Returns: the techno-economic analysis (cheme assess tea --json without the source): premises, capex build-up, flows, cash flow, results, scenarios, tornado, break-even values, Monte Carlo, findings; see docs/framework/tea.md; 404 without estimate/tea.yaml, 422 when it does not compute
| parameter | in | type | required | default | description |
|---|---|---|---|---|---|
rev |
query | string or null |
Responses:
200: Successful Response (application/json)422: Validation Error (application/json)
GET /api/layout/section.svg¶
Get Layout Section
A section at x= or y= (depth m thick) of the committed model at rev.
Returns: a section of the committed model at x= or y= (one of them), depth m thick (0 to 1000); 404 without a model, 400 for bad arguments
| parameter | in | type | required | default | description |
|---|---|---|---|---|---|
rev |
query | string or null | |||
x |
query | number or null | |||
y |
query | number or null | |||
depth |
query | number | 6.0 |
Responses:
200: Successful Response (application/json)422: Validation Error (application/json)
GET /api/status¶
Get Status
cheme status --json of the working tree, without running the gates (they may run commands); the gates are POST /api/checks/run.
Returns: the cheme status --json summary of the working tree, without evaluating the gates
No parameters.
Responses:
200: Successful Response (application/json)
GET /api/impact¶
Get Impact
cheme impact --json of the working tree: review-needed findings (info).
Returns: the cheme impact --json report of the working tree: {commit, findings}, every finding cheme.review-needed at level info, with its id
No parameters.
Responses:
200: Successful Response (application/json)
GET /api/interlocks¶
Get Interlocks
Returns: {rev, file, interlocks, columns (effect tags), rows: [{id, title, cause, condition, sheet, sil, cells}]}: the cause-and-effect list and matrix; 404 without control/cause-effect.yaml
| parameter | in | type | required | default | description |
|---|---|---|---|---|---|
rev |
query | string or null |
Responses:
200: Successful Response (application/json)422: Validation Error (application/json)
GET /api/issues¶
Get Issues
cheme issues --json of the working tree's plant: its GitHub issues as engineering items (read-only, cached as for the gates: project.issues.CACHE_S); 404 when plant.yaml declares no issues, 503 when they cannot be read (no token, no network).
Returns: the cheme issues --json report: the plant's GitHub issues as engineering items (type, gate, discipline, source, status), open_by_gate, blocking per stage and new links to the issue forms; see docs/framework/issues.md; cached two minutes; 404 when plant.yaml declares no issues, 503 when they cannot be read (no token, no network)
No parameters.
Responses:
200: Successful Response (application/json)
GET /api/control¶
Get Control
cheme control report --json of the working tree: loops, sequences, the narrative and the control philosophy with their review status and findings; 404 when the plant has none of them (control documentation is optional).
Returns: the cheme control report --json report of the working tree: loops, sequences, the narrative and the control philosophy with their review status and findings; see docs/framework/control.md; 404 without control records, 422 when they do not load
No parameters.
Responses:
200: Successful Response (application/json)
GET /api/streams¶
Get Streams
Returns: the stream table of process/flowsheet.yaml: streams (values with unit, provenance, source and stale flag, composition, calculated values, links with resolved/problem, imbalance, on_bfd), balances, nodes, bfd_connections (BFD connection id to the streams it represents, read from the built BFD sheet's represents: descriptions, else from the flowsheet; bfd_connections_from says which: sheet or flowsheet), cases, units, tolerance; 404 without a flowsheet, 422 for one that does not load or an unknown case
| parameter | in | type | required | default | description |
|---|---|---|---|---|---|
case |
query | string or null | |||
rev |
query | string or null |
Responses:
200: Successful Response (application/json)422: Validation Error (application/json)
GET /api/simulation¶
Get Simulation
process/simulation.yaml parsed, the run cheme process simulate --fill recorded in process/simulation-run.json (null without one), whether that record is stale against the inputs now, and one merged row per unit. 404 without the simulation file; 422 when it does not load or for an unknown case. A flowsheet that does not load leaves the spec and the record, with stale null and problem saying why.
Returns: {rev, file, run_file, case, cases, spec, run, stale, staleness, units, problem, findings}: spec is process/simulation.yaml parsed (simulator, property_package, components, tolerance, tear_streams, exclude, guesses, specs per step as written, with provenance); run the case's entry of process/simulation-run.json (null without one); stale whether that run was simulated from other inputs (model fingerprint; null without a run or when the flowsheet does not load), staleness {model_fingerprint, current_fingerprint, changed_files}; units one row per step {id, unit, status (simulated, excluded, refused, not-simulated), reason, spec, run}; findings the translation's; 404 without process/simulation.yaml, 422 when it does not load or for an unknown case
| parameter | in | type | required | default | description |
|---|---|---|---|---|---|
case |
query | string or null | |||
rev |
query | string or null |
Responses:
200: Successful Response (application/json)422: Validation Error (application/json)
GET /api/kinetics¶
Get Kinetics
The kinetic data files of experiments/kinetics/ with their points and default fits (cheme experiments fit-rate). 404 without any.
Returns: {rev, directory, files: [{file, data, fit, problem}]}: each kinetic data file of experiments/kinetics/ as declared and its default fit (cheme experiments fit-rate --json: a power law in the reaction's reactants, over 1 − Q/K when the reaction is reversible and K is known; fit.reverse says which), or the problem with either (where 1 − Q/K fails at a point, a forward-only fit with a note); a flowsheet that does not load is not needed; cheme export-static --exclude leaves out excluded files; 404 without data files or process files
| parameter | in | type | required | default | description |
|---|---|---|---|---|---|
rev |
query | string or null |
Responses:
200: Successful Response (application/json)422: Validation Error (application/json)
GET /api/library¶
Get Library
The reaction library (cheme chemistry library), each item marked when the plant has it.
Returns: {rev, entries}: the reaction library (cheme chemistry library), every entry (window, components, reactions, catalysts, model basis, sources), each item's in_plant saying what the plant has (a component: the plant's id with its CAS number, else null; a reaction: the same stoichiometry under its id; a catalyst: its id, with differs when the plant's has other data, so --add refuses it); without process files nothing is marked, and a flowsheet that does not load leaves the marks from the materials, reactions and catalysts
| parameter | in | type | required | default | description |
|---|---|---|---|---|---|
rev |
query | string or null |
Responses:
200: Successful Response (application/json)422: Validation Error (application/json)
GET /api/reactions¶
Get Reactions
process/reactions.yaml with what the flowsheet says about each reaction, the cheme process reactors rows, the reactive balances with their findings, each rate law with its units and k(T), and the catalysts of process/catalysts.yaml. 404 without the reactions file or the flowsheet; 422 when either does not load or for an unknown case.
Returns: {rev, file, case, cases, reactions, reactors, balance, kinetics}: each reaction as declared (stoichiometry, equation, phase, reversible, conversion, heat_of_reaction, equilibrium_constant with provenance, catalyst, sources) plus key_component, reaction_smiles (the reaction's external identifier, reactants>>products from the stoichiometry and the components' SMILES; null unless every component has one and every coefficient is whole), type (the reactor model it runs in: conversion, equilibrium, gibbs, mixed or null), units ({unit, kind, model, approach_K, conversion} per block or step naming it) and element_balance; reactors the cheme process reactors --json rows; balance {balances, findings} (the reactive balances and the reaction, reactor and balance findings of validate); per reaction its rate as declared (form, basis, driving, k {A, Ea, n, T_ref}, orders, adsorption, catalyst, temperature_range, provenance, source) and rate_law (null without a rate: {expression, k_expression, rate_unit, driving_unit, k_unit, catalyst, k_profile: [{temperature_K, k}], k_profile_from}, k(T) over the rate's temperature range, else its catalyst's window); kinetics {file, catalysts, findings}: each catalyst of process/catalysts.yaml as declared plus reactions (ids it catalyses) and units ({unit, kind, reactor, reactions, bed} per block or step holding it), the cheme.catalyst-* and cheme.process-catalyst findings (file null and catalysts empty without the file); a solved fixed bed is the bed of its reactors row, and each reactors row says its gas model (fugacity: ideal or peng_robinson); a reaction with a mechanism has microkinetics (null without one): {conditions: {unit, stream, temperature_K, pressures_bar}, missing, ...}, the cheme chemistry microkinetics --json analysis (coverages, TOF, degree of rate control, apparent Ea, orders) at the outlet of its first reactor, or missing naming why there is none; 404 without process/reactions.yaml or a flowsheet, 422 when either does not load or for an unknown case
| parameter | in | type | required | default | description |
|---|---|---|---|---|---|
case |
query | string or null | |||
rev |
query | string or null |
Responses:
200: Successful Response (application/json)422: Validation Error (application/json)
GET /api/validate¶
Get Validate
Returns: the cheme validate --json report of the working tree
No parameters.
Responses:
200: Successful Response (application/json)
GET /api/maturity¶
Get Maturity
cheme maturity --json of the working tree: the levels, requirement by requirement, the model basis, limitations and findings. Evaluated on every request (:func:~chemeascode.project.maturity.maturity_payload), one at a time; nothing is written (checked_at is the time of this evaluation, in the answer only; cheme maturity --write writes checks/maturity.json). Without through the engineering level runs the whole-repository validation, the dominant cost (some 30 s on a plant like ASU-1); through=predictive (or a lower level) skips it and reports the levels above as not-evaluated. 400 for an unknown level; 422 when the plant does not load.
Returns: the cheme maturity --json report of the working tree, evaluated on every request (one at a time) and never written; without through the engineering level runs the whole validation (some 30 s on ASU-1), through=predictive or lower skips it; see docs/framework/maturity.md; 400 for an unknown level
| parameter | in | type | required | default | description |
|---|---|---|---|---|---|
through |
query | string or null |
Responses:
200: Successful Response (application/json)422: Validation Error (application/json)
GET /api/session¶
Get Session
Returns: {token, header}: the per-launch token for POST /api/checks/run
No parameters.
Responses:
200: Successful Response (application/json)
POST /api/checks/run¶
Post Checks Run
Returns: the gates evaluated now on the working tree (not written); needs the token header
No parameters.
Responses:
200: Successful Response (application/json)
GET /api/checks¶
Get Checks
Returns: checks/status.json ({checks: []} when absent)
| parameter | in | type | required | default | description |
|---|---|---|---|---|---|
run |
query | boolean | false |
||
rev |
query | string or null |
Responses:
200: Successful Response (application/json)422: Validation Error (application/json)