[DOCS]

API
Reference

[BASE]

https://chemply.io/api/v1

Unified REST endpoints for chemical lookup, structural search, and regulatory compliance. JSON responses, predictable shapes, no SDK required.

[CONTENTS]

[AUTH]

Authentication

All API requests can be made without authentication (rate-limited to 100 req/min per IP). For higher limits, pass your API key via the `X-API-Key` header.

bash
curl -H "X-API-Key: YOUR_KEY" \
  https://chemply.io/api/v1/molecule/search?name=aspirin

[RATE_LIMITING]

Rate Limiting

Rate limit info is returned in response headers: - `X-RateLimit-Limit` — max requests per window - `X-RateLimit-Remaining` — remaining requests - `X-RateLimit-Reset` — Unix timestamp when the window resets Anonymous: 100 req/min. Authenticated: 1000 req/min (default, configurable per key).

[LOOKUP_LAYER]

Lookup Layer

GET/api/v1/molecule/:inchikey

Retrieve a molecule by InChIKey. Returns identifiers, names, properties, bioactivities, and compliance data.

[REQUEST]

bash
curl https://chemply.io/api/v1/molecule/BSYNRYMUTXBXSQ-UHFFFAOYSA-N

[RESPONSE]

json
{
  "success": true,
  "data": {
    "inchikey": "BSYNRYMUTXBXSQ-UHFFFAOYSA-N",
    "canonical_smiles": "CC(=O)OC1=CC=CC=C1C(O)=O",
    "molecular_formula": "C9H8O4",
    "molecular_weight": 180.16,
    "names": ["Aspirin", "Acetylsalicylic acid"],
    "identifiers": { "pubchem_cid": 2244, "cas": "50-78-2" }
  }
}
GET/api/v1/molecule/search

Search molecules by name, CAS number, PubChem CID, or ChEMBL ID. Supports fuzzy name matching.

[PARAMETERS]

Name
Type
Description
name
string
Molecule name (fuzzy)
cas
string
CAS Registry Number
pubchem_cid
integer
PubChem Compound ID
chembl_id
string
ChEMBL ID
limit
integer
Max results (default 20)
offset
integer
Pagination offset

[REQUEST]

bash
curl "https://chemply.io/api/v1/molecule/search?name=aspirin"

[RESPONSE]

json
{
  "success": true,
  "data": [ ... ],
  "meta": { "total": 3, "limit": 20, "offset": 0 }
}
POST/api/v1/molecule/batch

Batch lookup of up to 100 InChIKeys in a single request.

[REQUEST]

bash
curl -X POST https://chemply.io/api/v1/molecule/batch \
  -H "Content-Type: application/json" \
  -d '{"inchikeys": ["BSYNRYMUTXBXSQ-UHFFFAOYSA-N", "HEFNNWSXXWATRW-UHFFFAOYSA-N"]}'

[RESPONSE]

json
{
  "success": true,
  "data": [ ... ],
  "meta": { "found": 2, "not_found": 0 }
}

[SEARCH_LAYER]

Search Layer

GET/api/v1/search/similarity

Find structurally similar molecules using Tanimoto similarity on Morgan fingerprints (RDKit).

[PARAMETERS]

Name
Type
Description
smiles
string
Query SMILES (required)
threshold
float
Min similarity 0.0–1.0 (default 0.7)
fingerprint
string
Fingerprint type: morgan, ecfp6 (default morgan)
limit
integer
Max results (default 100, max 1000)

[REQUEST]

bash
curl "https://chemply.io/api/v1/search/similarity?smiles=CC(%3DO)OC1%3DCC%3DCC%3DC1C(O)%3DO&threshold=0.7"

[RESPONSE]

json
{
  "success": true,
  "data": [
    {
      "inchikey": "...",
      "canonical_smiles": "...",
      "similarity": 0.85
    }
  ],
  "meta": { "total": 12, "query_smiles": "CC(=O)OC1=CC=CC=C1C(O)=O" }
}
GET/api/v1/search/substructure

Find molecules containing a given substructure (RDKit substructure match).

[PARAMETERS]

Name
Type
Description
smiles
string
Substructure SMILES (required)
limit
integer
Max results (default 100, max 10000)

[REQUEST]

bash
curl "https://chemply.io/api/v1/search/substructure?smiles=c1ccccc1"

[RESPONSE]

json
{
  "success": true,
  "data": [ ... ],
  "meta": { "total": 4821 }
}

[COMPLIANCE_LAYER]

Compliance Layer

GET/api/v1/compliance/:inchikey

Get regulatory compliance status for a molecule across all frameworks (REACH, TSCA, Prop 65, CLP, SVHC).

[REQUEST]

bash
curl https://chemply.io/api/v1/compliance/BSYNRYMUTXBXSQ-UHFFFAOYSA-N

[RESPONSE]

json
{
  "success": true,
  "data": {
    "inchikey": "BSYNRYMUTXBXSQ-UHFFFAOYSA-N",
    "frameworks": [
      { "framework": "REACH", "status": "registered", "jurisdiction": "EU" },
      { "framework": "TSCA", "status": "listed", "jurisdiction": "US" }
    ]
  }
}
GET/api/v1/compliance/search

Search molecules by compliance framework, jurisdiction, or risk level.

[PARAMETERS]

Name
Type
Description
framework
string
e.g. REACH, TSCA, PROP65
jurisdiction
string
e.g. EU, US, CA
risk_level
string
e.g. high, medium, low
limit
integer
Max results (default 20)
offset
integer
Pagination offset

[REQUEST]

bash
curl "https://chemply.io/api/v1/compliance/search?framework=REACH&jurisdiction=EU"

[RESPONSE]

json
{
  "success": true,
  "data": [ ... ],
  "meta": { "total": 42, "limit": 20, "offset": 0 }
}

[ERRORS]

Error
Codes

All errors follow a consistent JSON envelope:

json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "status": 400
  }
}
Code
Status
Description
INVALID_SMILES
400
SMILES string could not be parsed
INVALID_INCHIKEY
400
Invalid InChIKey format
NOT_FOUND
404
Molecule not found
RATE_LIMIT_EXCEEDED
429
Rate limit exceeded
INTERNAL_ERROR
500
Unexpected server error