API Guide

CEMP API Usage Guide

CEMP API documentation, read-only database endpoints, BMS database queries, and exact task-status lookup are publicly accessible without registration or login. A token is required only for protected operations such as submitting compute jobs or accessing account-specific functions.

Public Access and API Keys

You can use all endpoints marked No in the tables below immediately, without creating an account. Public database access is not reduced to a preview or sample subset.

Login is optional and is needed only if you want to generate a personal token for protected compute submission endpoints. Log in for compute access.

Protected Compute Access

1. Obtain a Token for Compute Submission

Skip this section when using public database or task-status APIs. The CEMPAgent project uses /api/token/ only as the standard authentication entry for protected calls.

curl -X POST "https://cleanenergymaterials.cn/api/token/" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "YOUR_USERNAME",
    "password": "YOUR_PASSWORD"
  }'

import requests

base_url = "https://cleanenergymaterials.cn"

response = requests.post(
    f"{base_url}/api/token/",
    json={
        "username": "YOUR_USERNAME",
        "password": "YOUR_PASSWORD",
    },
    timeout=60,
)
response.raise_for_status()

token = response.json()["token"]
print("Token acquired successfully.")
print(token)

Async Jobs

2. Submit Compute Tasks and Query Status

Most Autocompute APIs are asynchronous. After submission, the server returns an encrypted_id. You should then call /api/check_task_status/ with the exact encrypted ID to fetch progress, download links, table previews, and figure URLs.

import requests

base_url = "https://cleanenergymaterials.cn"
token = "YOUR_TOKEN"

headers = {
    "Authorization": f"Token {token}",
}

with open("HTQC.xlsx", "rb") as f:
    submit_response = requests.post(
        f"{base_url}/autocompute/api/single_point_energy_gaussian/",
        headers=headers,
        files={"excel_file": f},
        timeout=300,
    )

submit_response.raise_for_status()
submit_payload = submit_response.json()
encrypted_id = submit_payload["encrypted_id"]
print("Task submitted:", encrypted_id)

status_response = requests.post(
    f"{base_url}/api/check_task_status/",
    json={"encrypted_id": encrypted_id},
    timeout=60,
)
status_response.raise_for_status()
status_payload = status_response.json()
print(status_payload)

{
  "status": "not_finished | success | failed",
  "download_urls": ["..."],
  "task_type": "...",
  "table_data_url": "...",
  "figure_data_url_dict": {
    "figure_name": "..."
  }
}

Core Endpoints

3. Core API Endpoints

The following endpoints are directly aligned with the routes used in the current CEMP project and in the CEMPAgent client implementation.

Method	Endpoint	Authentication	Description
POST	/api/token/	No	Exchange username and password for a reusable token.
POST	/generate_API/	Session	Browser helper route for logged-in users to obtain their current token on this page.
POST	/api/check_task_status/	No	Public exact-ID lookup for task progress and result links. The encrypted_id acts as the access key and should be kept private.
POST	/battery_manage_system/api/visual/	No	Read-only BMS metadata search, battery lookup, filtering, and visualization API.

Autocompute API

4. Selected Autocompute Endpoints

These endpoints are mounted under /autocompute/api/. They are token-authenticated and generally use multipart form upload with an Excel input file.

Method	Endpoint	Authentication	Description
POST	/autocompute/api/mdcompute/	Token	Submit a Gromacs molecular dynamics task from an Excel system file.
POST	/autocompute/api/single_point_energy_gaussian/	Token	Batch Gaussian single-point energy calculation.
POST	/autocompute/api/binding_energy_gaussian/	Token	Batch Gaussian binding energy calculation for dimers or complexes.
POST	/autocompute/api/pka_pkb_gaussian/	Token	Batch Gaussian pKa / pKb related workflow.
POST	/autocompute/api/ox_red_gaussian/	Token	Batch Gaussian oxidation / reduction property calculation.
POST	/autocompute/api/reaction_thermo_gaussian/	Token	Batch Gaussian reaction thermodynamics workflow.
POST	/autocompute/api/reaction_properties_gaussian/	Token	Batch Gaussian global reaction properties workflow.
POST	/autocompute/api/single_point_energy_orca/	Token	Batch ORCA single-point energy calculation.
POST	/autocompute/api/binding_energy_orca/	Token	Batch ORCA binding energy calculation.
POST	/autocompute/api/ox_red_orca/	Token	Batch ORCA oxidation / reduction property calculation.
POST	/autocompute/api/query_smiles_to_name/	Token	Resolve molecular names from submitted SMILES spreadsheets.

Ionic Liquid API

5. Selected Ionic Liquid Endpoints

The current repository also exposes JSON and prediction APIs under the /ionic_liquid/ route tree.

Method	Endpoint	Authentication	Description
POST	/ionic_liquid/api/ionic_liquid_predict_excel/	Token	Batch ionic-liquid property prediction using an Excel file.
POST	/ionic_liquid/api/ionic_liquid_predict_SMILES/	Token	Predict ionic-liquid properties from a single SMILES input.
POST	/ionic_liquid/api/similarity_search/	No	Public read-only search for similar ionic-liquid structures.
POST	/ionic_liquid/api/property_filter/	No	Public read-only filtering of ionic-liquid candidates by property constraints.
GET	/ionic_liquid/api/Cation_QC_data, /ionic_liquid/api/Anion_QC_data, /ionic_liquid/api/IL_Tm_conductivity_ECW_data, /ionic_liquid/api/IL_ML_data	No	Public structured database APIs with pagination, search, and sorting; all records are queryable rather than only a sample subset.
GET	/ionic_liquid/api/ILThermo_Total_data, /ionic_liquid/api/ILThermo_Mixture_systems, /ionic_liquid/api/ILThermo_Mixture_observations, /ionic_liquid/api/ILThermo_Mixture_compositions, /ionic_liquid/api/ILThermo_Mixture_meta	No	Public ILThermo total and mixture database APIs, including system, observation, composition, and filter metadata.

Best Practices

6. Practical Notes

Do not expose your raw password or token in shared notebooks, screenshots, or public repositories.
Autocompute interfaces are mostly asynchronous. Receiving an encrypted_id usually means the task has been accepted, not finished.
When the API returns relative paths such as /media/..., combine them with the CEMP base URL before downloading.
For production scripts, implement timeout handling, retry logic, and status polling intervals instead of querying in a tight loop.