REST API

The server describes itself at /openapi.json, with interactive documentation at /docs. This page is the map.

Documents

Route	Does
GET /api/session	The open documents, the one to show first, and what the server can do.
POST /api/documents	A new document: empty, from a document’s JSON (document), or imported (format, data).
GET /api/documents/{id}	The document, its revision (also as ETag), warnings, and its file.
PUT /api/documents/{id}	Replace it. Needs If-Match with the revision it is based on.
PUT /api/documents/{id}/canvas	Replace the drawing (KET); species and reactions are derived from it.
POST /api/documents/{id}/import	Draw structures from format/data, appended or replacing.
POST /api/documents/{id}/clean	Standard bond lengths and angles for every molecule; a molecule it cannot clean without changing its stereochemistry is left and named in warnings.
POST /api/documents/{id}/embed	3D structures for species (all by default), count conformers each; replace re-embeds. Species that fail are named in warnings; when nothing changes, the revision stays.
POST /api/documents/{id}/inputs	One writer’s input for several species with one spec, as JSON or a zip (format); refused species are listed with the reasons.
POST /api/documents/{id}/submit	Inputs for species (all by default) with program (orca, vibeqc) and spec, submitted to vibe-queue; embeds what has no 3D structure, records the jobs and runs, answers with submitted and refused. 503 without vibe-queue.
GET /api/documents/{id}/runs	The document’s runs with their state in vibe-queue.
POST /api/documents/{id}/view	Shows species in vibe-view as a QVF; 422 without a 3D structure, 503 without vibe-view. GET /api/session says which route applies ("viewer").
PATCH /api/documents/{id}/species/{species}	Set a compound number, multiplicity or name.
GET /api/documents/{id}/report	Formula, masses, identifiers and checked name per species.
GET /api/documents/{id}/export/{format}	The document as a file; ?download=true names it.
POST /api/documents/{id}/save	Write it back to the file the server opened it from.
DELETE /api/documents/{id}	Close it.

Every write names the revision it is based on: If-Match on PUT, a revision field on the others. A stale write answers 409 (412 for PUT) with the current revision; read the document again and retry. Writes also take actor (human, agent or system) and client (for example rest or mcp), which go into the document’s provenance.

Without storing anything

Route	Does
POST /api/convert	format/data to a document.
POST /api/clean	A posted document with its drawing cleaned, and how many molecules were.
POST /api/chem/embed3d	3D conformers for one smiles, best first, with force-field energies.
POST /api/report	The report for a posted document.
POST /api/export/{format}	A posted document as a file.
POST /api/documents/validate	Whether a JSON value is a valid document, with every problem.
GET /api/queue	Whether vibe-queue is installed and serving, and which programs it can run.
POST /api/queue/runs/{run}/cancel	Cancel a run; 409 when it has finished.
GET /api/schema/document	The document’s JSON schema.
GET /api/writers, POST /api/inputs	The input writers; see input writers.

Binary data, a QVF archive, goes into data base64-encoded with "encoding": "base64" (on POST /api/documents, /import and /convert). GET /api/session says whether QVF is available ("qvf").

Refusals answer 422 with the reasons, under detail.reasons or detail.errors. A figure export on a machine without the drawing libraries (see installation) answers 503, with the fix in detail.reasons.