API Reference¶
ChemVault exposes an optional FastAPI interface for supported database reads,
exports, UniProt gene-symbol resolution, PubChem protein-search jobs, scientific
jobs, structure consolidation, and fingerprint artifact retrieval. The API does
not expose every operation available in the Streamlit interface. Routine use
through chemvault does not require starting FastAPI; see the Usage guide.
Starting FastAPI¶
From the working directory containing the SQL/ database directory, run
FastAPI in the Python environment where ChemVault is installed:
python -m uvicorn api.main:app
The --reload option may be added for source development. It is not required
to operate the API. The default base URL is http://127.0.0.1:8000, and
interactive OpenAPI documentation is available at
http://127.0.0.1:8000/docs.
Database identifiers may contain letters, numbers, underscores, and hyphens.
Database operations require an existing SQL/<database_id>.db in the active
working directory; the API does not provide an endpoint for creating databases.
When using the Streamlit API-client mode, start both processes from the same
working directory so that they refer to the same SQLite databases.
Endpoint inventory¶
| Method | Path | Capability |
|---|---|---|
GET |
/health |
Service health. |
GET |
/protein-identifiers/uniprot/organisms |
Ordered supported-organism catalog. |
GET |
/protein-identifiers/uniprot |
Resolve one gene symbol and organism to one reviewed UniProt target. |
POST |
/databases/{database_id}/scientific-runtime/activate |
Activate recovery for scientific jobs in one database. |
POST |
/databases/{database_id}/jobs/pubchem_protein_search |
Launch a persisted PubChem protein-search job. |
GET |
/databases/{database_id}/jobs/pubchem_protein_search/{job_id} |
Read PubChem job status. |
POST |
/databases/{database_id}/jobs/pubchem_protein_search/{job_id}/cancel |
Cancel an active PubChem job. |
POST |
/databases/{database_id}/jobs/pubchem_protein_search/{job_id}/finalize |
Register a completed PubChem build exactly once. |
POST |
/databases/{database_id}/jobs/harmonsmile |
Launch a HARMONSMILE scientific job. |
POST |
/databases/{database_id}/jobs/modelability_index |
Launch a MODELABILITY INDEX scientific job. |
GET |
/databases/{database_id}/jobs/harmonsmile/active |
Find the active HARMONSMILE job for a table. |
GET |
/databases/{database_id}/jobs/{job_id} |
Read generic persisted scientific-job status. |
GET |
/databases/{database_id}/tables |
List user-visible tables. |
GET |
/databases/{database_id}/operations |
Read operation history newest first. |
GET |
/databases/{database_id}/tables/{table_name}/metadata |
Read columns, row count, schema, provenance, and available summaries. |
GET |
/databases/{database_id}/tables/{table_name}/metrics |
Read row and optional grouped counts. |
GET |
/databases/{database_id}/tables/{table_name}/preview |
Preview selected columns. |
GET |
/databases/{database_id}/tables/{table_name}/export |
Download a complete table or selected columns as UTF-8 CSV. |
POST |
/databases/{database_id}/tables/{table_name}/structure-consolidation |
Create an ACTIVITY LABELS structure-level table. |
GET |
/databases/{database_id}/tables/{table_name}/modelability-index/fingerprints/export |
Download one validated fingerprint artifact as .npz. |
The route definitions in api/main.py and response models in api/schemas.py
define the HTTP contract. The routes listed here are the implemented endpoints;
the API is not a general-purpose interface for all Streamlit operations.
UniProt target resolution¶
Supported organisms¶
GET /protein-identifiers/uniprot/organisms
The response contains the backend-defined ordered catalog with organism ID, scientific name, and common name.
Resolve a gene symbol¶
GET /protein-identifiers/uniprot?gene_symbol=LEPR&organism_id=9606
Successful resolution returns the gene symbol, organism identity, UniProt accession, entry name, protein name, and reviewed status. The resolution is strict: invalid input returns 422, no reviewed match returns 404, ambiguity returns 409, and upstream UniProt failure returns 502.
Direct UniProt-accession entry is a Streamlit input mode and does not require a separate resolver endpoint.
Public persisted-job status¶
Scientific and PubChem job-status endpoints use a shared response schema. The following JSON illustrates its fields; the values are examples, not an observed job:
{
"job_id": "job-1",
"job_type": "harmonsmile",
"status": "running",
"database_id": "example",
"stage": "running",
"progress": 0.4,
"message": "HARMONSMILE chunk 1/3",
"created_at": "2026-07-03T10:00:00+00:00",
"updated_at": "2026-07-03T10:00:10+00:00",
"started_at": "2026-07-03T10:00:01+00:00",
"finished_at": null,
"error": null,
"result": null,
"cancellable": true
}
Supported lifecycle states are pending, running, completed, failed, and
cancelled. HTTP 201 alone does not establish workflow completion: inspect
the returned status, which can already be completed for a reused result.
Successful completion has status=completed, progress=1.0, and a result
summary in result; a persisted workflow failure has status=failed and an
error.
Internal request metadata, worker process IDs, heartbeats, and cancellation
timestamps are not public status fields.
cancellable describes the persisted job's current capability; it is not a
promise that every job type has a public cancellation endpoint. PubChem has an
explicit cancellation route. HARMONSMILE and MODELABILITY INDEX currently do
not.
Execution contracts¶
PubChem protein-search jobs¶
PubChem execution uses a dedicated persisted-job adapter and an external worker process. Launching creates the job and starts that worker:
POST /databases/example/jobs/pubchem_protein_search
Content-Type: application/json
{
"proteins": ["P34971"],
"target_identity": {
"input_mode": "uniprot_accession",
"uniprot_accession": "P34971"
}
}
proteins is a non-empty list of accession strings. The target-centered UI
uses one biological target. The optional target_identity payload is permitted
only when proteins contains exactly one accession and must identify that same
target. Launch returns HTTP 201 with the persisted job status; inspect the
PubChem-specific status endpoint to determine the workflow outcome.
Cancellation is supported for active PubChem jobs; repeated cancellation of an already terminal job returns its terminal status. Finalization requires a completed job and registers its base-table metadata and build operation exactly once. Finalization is not a separate certification of source-record completeness. Invalid job type or state returns 409; invalid launch input returns 422.
Generic scientific jobs¶
application.scientific_jobs is the application boundary for HARMONSMILE
and MODELABILITY INDEX jobs. Each registered workflow supplies creation and
execution hooks. Launch returns a persisted job status and starts an in-process
executor for pending work. A compatible completed MODELABILITY INDEX result may
be returned without another calculation. The generic status endpoint reads the
persisted job record.
PubChem uses a separate worker process and dedicated routes. HARMONSMILE and MODELABILITY INDEX use registered scientific-job execution in the active Streamlit or FastAPI process. They share a public status schema and SQLite persistence, but not an execution engine.
HARMONSMILE launch¶
POST /databases/example/jobs/harmonsmile
Content-Type: application/json
{
"table_name": "main",
"cid_column": "CID"
}
The source table and CID column must exist. Missing resources return 404 and an invalid column returns 422.
The active lookup requires table_name:
GET /databases/example/jobs/harmonsmile/active?table_name=main
It returns the equivalent active job or null.
MODELABILITY INDEX launch¶
POST /databases/example/jobs/modelability_index
Content-Type: application/json
{
"table_name": "activity_subset_IC50_structure_consolidated",
"fingerprint_type": "morgan"
}
The table must be an eligible ACTIVITY LABELS consolidated source. A compatible completed analysis can be returned immediately; otherwise a pending job is executed through the scientific runtime. Missing resources return 404 and an invalid scientific source returns 422.
Scientific runtime activation¶
POST /databases/example/scientific-runtime/activate
Activation runs once per database path in the current process. It marks
orphaned MODELABILITY INDEX jobs according to their non-resumable contract,
requeues eligible HARMONSMILE jobs, starts their executors, and returns
recovered HARMONSMILE job snapshots with table_name. It does not create a
distributed worker service.
Local and API-client semantics¶
clients.backend_gateway.BackendGateway provides Streamlit with a common
interface for supported operations:
- when
CHEMVAULT_API_URLis unset, the local backend calls application and service functions directly; - when
CHEMVAULT_API_URLis set, the HTTP backend calls the corresponding FastAPI endpoints.
API-client mode covers only operations implemented by the HTTP backend; it does not make all local Streamlit functionality available over HTTP. See the Usage guide for configuration and launch instructions.
Local HARMONSMILE and MODELABILITY launches run a daemon thread in the Streamlit process. HTTP launches run one in the FastAPI process. PubChem launch starts the external worker from the selected backend process. All modes persist status in the selected database and the UI polls until a terminal state.
Transport failures are distinct from persisted workflow failures. An
unreachable backend or invalid HTTP response raises BackendGatewayError; it
does not establish that the persisted scientific job failed. Only the stored
job status is authoritative for workflow success or failure. The gateway never
silently falls back to local execution.
Database inspection¶
Tables and operation history¶
GET /databases/{database_id}/tables returns user-visible table names.
GET /databases/{database_id}/operations returns recorded processing
operations, newest first, including operation type, source and target table,
source columns, timestamp, status, and details when available. Processing
history records application operations; it is distinct from the provenance of
the source data.
Metadata and schema¶
GET /databases/example/tables/main/metadata
{
"database_id": "example",
"table": "main",
"columns": ["CID", "SMILES"],
"row_count": 100,
"preview_limit": 10,
"read_only": true,
"schema": [
{
"cid": 0,
"name": "CID",
"data_type": "TEXT",
"not_null": false,
"default_value": null,
"primary_key": false
}
],
"origin": "protein_search",
"source_table": null,
"structure_consolidation_summary": null,
"target_identity": null
}
This response is an illustrative schema example, not the output of a specific
dataset. The read_only field describes the HTTP table interface; it does not
mean that the underlying SQLite database cannot be changed through other
supported workflows. Target identity and consolidation summaries are returned
only when supported by persisted metadata. Their presence documents provenance
or processing results, not independent source-data completeness.
GET /metrics returns row_count and group_count; the optional
group_column parameter selects a valid grouping column. These counts refer
to database records or groups, not necessarily to distinct compounds, bioassays,
or molecular structures. GET /preview accepts repeated columns parameters
and returns at most ten records.
Structure consolidation¶
POST /databases/example/tables/activity_subset_IC50/structure-consolidation
The endpoint creates an eligible ACTIVITY LABELS structure-level table and
returns its generated name and a summary of source activity records, eligible
records, distinct molecular structures, consolidated structures, class counts,
exclusions, contributing observations, and quantitative-reference selection.
The response fields use different populations and denominators; these counts
must not be interpreted as interchangeable. Their exact names are defined by
StructureConsolidationResponse in api/schemas.py. Missing resources return
404; scientific ineligibility returns 422.
Downloads¶
Table CSV¶
GET /databases/example/tables/main/export?columns=CID&columns=SMILES
The response is UTF-8 text/csv and includes all records for the requested
columns in request order. Omitting columns exports the complete table.
Unknown columns return 422. This endpoint does not apply the UI's filtered
subgroup or Structured activity filters.
Fingerprint artifact¶
GET /databases/example/tables/activity_subset_IC50_structure_consolidated/modelability-index/fingerprints/export?analysis_identity=<identity>&fingerprint_type=morgan
The response is application/octet-stream with the backend-generated .npz
filename. The endpoint retrieves an existing fingerprint artifact only after
validating the source table, analysis identity, and fingerprint type. It does
not generate new fingerprints. A stale identity or a missing, corrupt, or
incompatible artifact returns 409.
The other three MODELABILITY INDEX downloads—nearest-neighbor CSV, Murcko relationships CSV, and analysis JSON—are available from the Streamlit result card; they are not separate HTTP endpoints in this API.
Current boundary¶
The API does not create or delete databases, expose general table mutation, or operate as a distributed worker platform. Filtered subgroup export and Structured activity CSV export remain Streamlit workflows. The supported PubChem jobs, scientific jobs, structure consolidation, and fingerprint artifact retrieval are explicit exceptions to a read-oriented HTTP interface.
The api/, application/, and services/ layers remain independent of
Streamlit and st.session_state.