Skip to the endpoints
StructSubAPI
REFERENCE

Every endpoint,
with a console attached.

Upload a structure once, then work within its session: select atoms, substitute fragments, optimise, analyse and export. Each endpoint below expands to its exact request body, its response and a Try it out button that calls this server.

Start from the Python quickstart How sessions work
BASE URL

This server

Every path below is relative to the address in your browser's bar. Use that same address in your scripts.

AUTHENTICATION

Account access

Anonymous uploads need no sign-in. Account operations use a short-lived token from sign-in as Authorization: Bearer …. There are no personal API keys - see API access & keys.

SESSIONS

Upload once

POST /sessions returns a session ID. Include it in subsequent request paths to access the structure and its edit history.

LONG WORK

Some calls queue

A response with queued: true carries a job ID. Poll /jobs/{job_id} until it reports done, failed or cancelled.

A completed calculation is not necessarily a converged one. Optimisation responses carry report.converged, max_force and any warnings. UFF chemistry preparation is automatic. Both structure.chemistry_preparation and report.chemistry_preparation expose its status, reuse eligibility and charge warnings, including in background-job results. provisional chemistry remains uncertain even when geometry converges. Read them before using the geometry - the request succeeding only means the calculation ran.

Every endpoint

The full reference, with a console attached to each route, is below. This index is the same schema in plain HTML.

service

MethodPathWhat it does
GET/apiService identification
GET/backendsRelaxation backends, with the licence of each
GET/citeHow to cite StructSub, in every format it can be downloaded in
GET/cite/{citation_format}The citation in one format, as a file to import
GET/elementsThe element colour table the interface draws with
POST/fragments/previewTurn a fragment specification into 3D, without using it
GET/guestsThe catalogued guest molecules, for a menu
POST/guests/previewWhat a name, a SMILES string or a drawing turns into
GET/guests/searchFind a guest by name or formula: the catalogue first, then the constants database
GET/healthLiveness and current load
GET/ions/mobileEvery ion there are bond-valence parameters for, as element and charge; with ``session``, also the ions its structure holds, each with the charge it carries there, and whether it is a framework with organic linkers
GET/libraryThe built-in fragment catalogue
GET/monomersEvery residue and cap a written sequence can name
GET/residuesThe twenty amino acids, as substitutable residues

sessions

MethodPathWhat it does
GET/build/candidatesThe structure types a composition could be built in
GET/build/moleculesMolecular identities for building, without thermodynamic calculations
GET/build/prototypesEvery structure type a composition can be matched to
GET/build/space-groupsEvery space group a crystal can be built in, in its standard setting
GET/build/zeolitesEvery zeolite framework type that can be generated from its topology
GET/build/zeolites/resolveFind the zeolite a name refers to, with the exact specification that builds it
POST/sessionsUpload a structure and start an editing session
POST/sessions/buildBuild a structure from a specification and start a session on it
POST/sessions/projectOpen a user-owned project in temporary memory
DELETE/sessions/{session_id}Discard a session and free the structures it holds
GET/sessions/{session_id}The session's current structure and history
GET/sessions/{session_id}/downloadDownload the current structure
GET/sessions/{session_id}/export/formatsEvery file format the current structure can be exported to
POST/sessions/{session_id}/redoStep forward again after an undo
POST/sessions/{session_id}/undoStep back one operation

billing

MethodPathWhat it does
POST/cloud/billing/checkoutBegin an upgrade, and say where to send the browser
POST/cloud/billing/portalWhere an existing customer manages their own plan, card and invoices
POST/cloud/billing/webhookStripe's account of what happened, which is the only one that counts

account

MethodPathWhat it does
GET/cloud/configWhat the browser needs before anybody has signed in
POST/cloud/feedbackRecord a rating of the site, with or without an account
GET/cloud/feedback/summaryHow the site is rated so far
POST/cloud/groupsCreate
GET/cloud/groups/currentState
POST/cloud/groups/invitationsInvite
POST/cloud/groups/invitations/acceptAccept
DELETE/cloud/groups/invitations/{invitation_id}Revoke
DELETE/cloud/groups/members/{member_id}Remove
PATCH/cloud/groups/members/{member_id}Role
GET/cloud/meWho this is and what they may do
POST/cloud/onboarding/webhookVerified Clerk signup events for founder onboarding emails.
POST/cloud/quoteWhat a calculation will cost, before it is run
GET/cloud/workspacesWorkspaces

jobs

MethodPathWhat it does
GET/cloud/jobsThe caller's own background calculations, newest first, without results
DELETE/jobs/{job_id}Request cancellation without waiting for the session lock
GET/jobs/{job_id}A job's state, and its result once finished
POST/jobs/{job_id}/applyMake a finished background optimisation an edit of its session
POST/jobs/{job_id}/openOpen the structure a background calculation ran on, as a new session
DELETE/jobs/{job_id}/resultDelete a finished job, its result and the structure it ran on

frameworks

MethodPathWhat it does
POST/frameworks/describeDescribe building units without matching anything
POST/frameworks/generateBuild a framework on a net and start a session on it
POST/frameworks/matchWhich framework topologies these building units can form
POST/frameworks/named/{mof_id}/openOpen a named framework (MOF-5, UiO-66, ...) as a new session
POST/frameworks/openOpen a unit for workspace editing using the same reader as description
POST/frameworks/polymerJoin marked units in list order into a periodic chain without a named net
GET/frameworks/saltWhich library SBUs MOFs made from this metal salt contained
GET/frameworks/saltsWhat the library's search box completes: salts with formulas, motif names, framework names
GET/frameworks/sbu-searchLibrary SBUs for a motif name, a named framework or a metal salt
GET/frameworks/sbusThe metal SBU library, most common first
GET/sessions/{session_id}/building-unitReturn a finite unit specification carrying its edited bonds and geometry
POST/sessions/{session_id}/deconstruct/unitOne deconstructed unit as a building unit for the framework builder

analysis

MethodPathWhat it does
POST/membrane/compareA finished membrane result against measured membranes
POST/membrane/solveThe membrane equations on supplied isotherms and transport data
POST/sessions/{session_id}/analyseDiffraction, topology, stacking, porosity and open metal sites
GET/sessions/{session_id}/analysis/exportThe last characterisation as tables, in the same formats
POST/sessions/{session_id}/clashesFind overlapping atoms: pairs far closer than any bond allows
POST/sessions/{session_id}/deconstructBreak the framework into its distinct building units
GET/sessions/{session_id}/deconstruct/downloadDownload one building unit as a file
POST/sessions/{session_id}/guests/breakthroughBreakthrough of a gas mixture through a packed column of this framework
POST/sessions/{session_id}/guests/diffusionDiffusivity of guests in the rigid framework, by molecular dynamics
POST/sessions/{session_id}/guests/dockFind where one guest binds most strongly
POST/sessions/{session_id}/guests/flexibleBreathing of a flexible framework: GCMC on each form, compared by OFAST
POST/sessions/{session_id}/guests/gcmcAdsorption by grand canonical Monte Carlo, one simulation per pressure
POST/sessions/{session_id}/guests/isothermHenry's constant, the isosteric heat, and an adsorption isotherm
POST/sessions/{session_id}/guests/membraneGas permeation through a defect-free membrane of this framework
POST/sessions/{session_id}/guests/selectivityHow well this framework separates a mixture
POST/sessions/{session_id}/ions/diffusionTracer diffusivity at each temperature, the activation energy and the conductivity at 300 K, by molecular dynamics with the bond-valence force field or MACE-MP-0
POST/sessions/{session_id}/ions/hopThe rate-limiting hop's barrier by climbing-image NEB, with the bond-valence force field or MACE-MP-0, started along the energy landscape's path
POST/sessions/{session_id}/ions/migrationThe bond-valence site energy of a mobile ion, and its percolation barriers
POST/sessions/{session_id}/ions/voltageThe average voltage of an electrode against the ion's metal, with its theoretical capacity, energy density and volume change, from MACE-MP
POST/sessions/{session_id}/mechanicsCalculate elastic properties on a copy; keep the session unchanged
GET/sessions/{session_id}/mechanics/{result_id}/exportThe same calculation as tables: CSV, TSV, Markdown, a spreadsheet or JSON
POST/sessions/{session_id}/pxrd/compareCompare calculated patterns against the measured one
DELETE/sessions/{session_id}/pxrd/experimentalDetach one measured pattern, or every one when none is named
GET/sessions/{session_id}/pxrd/experimentalA measured pattern in this session: the active one unless ``dataset`` names another
POST/sessions/{session_id}/pxrd/experimentalAttach a measured powder pattern to the session
POST/sessions/{session_id}/pxrd/experimental/{dataset}/activeMake one loaded pattern the one comparisons use
POST/sessions/{session_id}/pxrd/refine-cellThe cell the measured pattern asks for, reached without changing the chemistry
POST/sessions/{session_id}/reportA result, or the whole session (``kind: "project"``), as a written report
POST/sessions/{session_id}/stack/fitRank AA, AB and slip stacks against the uploaded pXRD; leave the structure unchanged
POST/sessions/{session_id}/stack/fit/previewCompare one fitted candidate with the measurement, without applying it
POST/sessions/{session_id}/strainSoft points and strain distribution of a relaxed copy; the session is unchanged
GET/sessions/{session_id}/strain/{result_id}/exportThe strain analysis as tables: a summary, every coordinate and every bond
POST/sessions/{session_id}/topology/netThe topological net over the real geometry, for drawing
POST/sessions/{session_id}/vibrationsNormal modes and an estimated infrared spectrum of a relaxed copy; the session is unchanged
GET/sessions/{session_id}/vibrations/{result_id}/exportThe modes and spectrum as tables
GET/sessions/{session_id}/vibrations/{result_id}/modes/{index}One normal mode's displacement of every atom, largest 1, in the input atom order

names

MethodPathWhat it does
GET/names/compounds/{compound_id}One compound: identity, derived fields, and whether structsub catalogues it
GET/names/lookupWhat a typed name means, for when it is committed (not while typing)
GET/names/suggestCompletions for what is being typed: compounds and named frameworks

editing

MethodPathWhat it does
POST/sessions/{session_id}/atomsAdd one atom, at a position or onto an existing atom
POST/sessions/{session_id}/atoms/deleteDelete atoms, reporting the valences left open
POST/sessions/{session_id}/bond-ordersPerceive bond orders, coordination bonds included
POST/sessions/{session_id}/bondsAdd persistent connectivity used by rendering and force-field optimisation
POST/sessions/{session_id}/bonds/deleteRemove one bond, leaving every atom where it is
POST/sessions/{session_id}/bonds/delete-selectedRemove selected bonds as one edit; never delete their endpoint atoms
POST/sessions/{session_id}/bonds/orderChange one bond's order
POST/sessions/{session_id}/bonds/ordersChange selected bonds together, with one history entry and exact images
POST/sessions/{session_id}/curateFirst-pass cleaning of a crystal that has overlapping or disordered atoms
POST/sessions/{session_id}/functionaliseReplace single-atom sites with a functional group
POST/sessions/{session_id}/geometrySet a distance, angle or dihedral to a value
POST/sessions/{session_id}/guestsDrop unbound guest molecules - solvent, counterions - from a framework
POST/sessions/{session_id}/guests/loadFill the pores with guest molecules, to a requested loading
POST/sessions/{session_id}/hydrogensAdd missing hydrogens
POST/sessions/{session_id}/mechanics/{result_id}/applyApply Mechanical Reference
POST/sessions/{session_id}/prepare-biomoleculePrepare AMBER/CHARMM hydrogens and optionally add periodic water; undoable
POST/sessions/{session_id}/pxrd/refine-cell/applyMake the last refined cell an edit, if nothing has changed since it was refined
POST/sessions/{session_id}/relaxRelax the current structure
POST/sessions/{session_id}/replace-atomChange selected atoms to another element without adding a fragment
POST/sessions/{session_id}/selectFind sites, without changing anything
POST/sessions/{session_id}/stackTurn the open layer into a bulk stack
POST/sessions/{session_id}/stack/fit/applyApply the selected fit as one undoable stack edit, preserving its fitted spacing
POST/sessions/{session_id}/strain/{result_id}/applyLoad the relaxed reference or the deformed structure as an undoable edit
POST/sessions/{session_id}/substituteReplace selected sites with a fragment
POST/sessions/{session_id}/vibrations/{result_id}/applyLoad the relaxed structure the modes belong to, as an undoable edit

loading

MethodPathWhat it does
POST/sessions/{session_id}/ions/applyApply
POST/sessions/{session_id}/ions/configurationsGenerate
POST/sessions/{session_id}/ions/previewPreview