2. MolClass REST service

REST API and MCP integrations

Service boundaries

The public deployment is molclass.chemgrid.org. A local Compose installation exposes FastAPI at http://127.0.0.1:8000 and the Spring Boot predictor at http://127.0.0.1:8082. A reverse proxy can expose both under one origin.

• /api/v1 (FastAPI): datasets, uploads/imports, model definitions/reviews, registration jobs, and public molecule-card data.
• /api/v3 (predictor): molecule lookup, substructure search, published models, saved predictions, and prediction on indexed molecules.

These replace the old PHP endpoints such as /api/compound and /api/model. Do not use the historical Edinburgh hostnames or replace slashes in an InChI by underscores. Encode query parameters normally; the current lookup interface documents SMILES and InChIKey.

Read-only lookup

Method	Path	Purpose
GET	/api/v1/datasets?limit=250&offset=0	Catalog with total and pagination
GET	/api/v1/model-datasets	Model-eligible datasets and targets
GET	/api/v1/model-datasets/{datasetId}	Target labels and support counts
GET	/api/v1/model-options	Available algorithms, selectors, and profiles
GET	/api/v3/models?limit=100	Published models and available holdout metrics
GET	/api/v3/molecules?query=...&limit=25	Identity/name/SMILES lookup
GET	/api/v3/molecules/substructure?smiles=...&limit=25	Substructure search
GET	/api/v3/molecules/{id}	Molecule identity and scaffold information
GET	/api/v3/molecules/{id}/structure.svg	Structure depiction
GET	/api/v3/molecules/{id}/predictions?limit=200	Saved history without submitting work

curl --fail 'https://molclass.chemgrid.org/api/v1/datasets?limit=250&offset=0'
curl --fail 'https://molclass.chemgrid.org/api/v3/models?limit=100'
curl --fail --get 'https://molclass.chemgrid.org/api/v3/molecules'   --data-urlencode 'query=CC(=O)Oc1ccccc1C(=O)O'   --data-urlencode 'limit=25'

For the dataset catalog, continue with offset until total records have been retrieved. Model-list limits and saved-history limits are bounded; do not assume the dataset pagination contract applies to every endpoint.

Predict an indexed molecule

POST /api/v3/models/{modelDefinitionId}/molecules/{moleculeId}/predict

Choose IDs from lookup responses, not from a historical example. The synchronous response includes the predicted class, distribution, responseStrength, and available applicability fields. Saved history calls confidence confidenceScore and includes build identity. Preserve null applicability values as unknown.

To reuse results, match the molecule and published model build ID, not just the model name or definition ID. History is newest-first and capped at 200 entries; hitting the cap does not prove older results are absent.

Register a new SMILES and predict

POST /api/v1/molecules/predict accepts:

{"smiles":"CC(=O)Oc1ccccc1C(=O)O","model_definition_id":1}

Replace the example model ID with one currently published. A successful submission returns HTTP 202 with jobId; it is not a completed prediction. Poll GET /api/v1/jobs/{jobId}. Stop on SUCCEEDED, FAILED, or CANCELLED, and inspect result or the error. Running jobs can include stage, completed/total counts, and progress percentage. Progress measures completed work, not estimated time. Retry transient polling failures using the same job ID rather than resubmitting.

Anonymous callers must choose one model. The current registration implementation allows 100 submissions per IP per UTC day and returns HTTP 429 with DAILY_QUOTA_EXCEEDED when exhausted. A valid X-MolClass-Api-Key exempts this registration quota and permits omission of model_definition_id, requesting every currently published build missing a saved result. Multi-model results include successes and an errors list; inspect both.

This registration route remains available independently of training-data intake/configuration flags because it uses approved models. Other routes can have their own deployment controls; the registration quota is not a universal statement about all API requests.

Upload and model-management workflow

1. POST /api/v1/uploads submits an SDF for analysis.
2. GET /api/v1/uploads/{uploadId} and GET /api/v1/jobs/{jobId} expose analysis state.
3. POST /api/v1/uploads/{uploadId}/imports submits the confirmed import choices.
4. GET /api/v1/imports/{importRunId} reports progress and outcomes.
5. Discover eligible targets/options, then POST /api/v1/model-definitions creates training intent.
6. Review the completed build. Administrative POST /api/v1/model-builds/{buildId}/decision requires the configured approval bridge and X-MolClass-Review-Token.

Training-data writes require deployment authorization/configuration. See the repository contracts for request schemas rather than adapting retired PHP examples.

MCP access

The bundled MCP server exposes list_models, search_molecule, search_molecule_by_structure, get_molecule, get_predictions, predict, submit_and_predict, and usage_status.

Set MOLCLASS_BASE_URL to the predictor origin and MOLCLASS_API_URL to FastAPI. For the public reverse-proxied deployment both can use https://molclass.chemgrid.org. A server-issued MOLCLASS_API_KEY enables the authenticated registration behavior described above. Keep keys in client/server configuration, never URLs or committed files.

References: prediction API, registration, import, model creation.