# cfy-webservice

> Classifies chemical structures given as SMILES into the ChemOnt taxonomy (ClassyFire-style: kingdom, superclass, class, subclass, direct parent, alternative parents). JSON over HTTP, no authentication, no rate limit.

## How to call it

- POST /classify with header `Content-Type: application/json`.
- One compound: `{"smiles": "CN1C=NC2=C1C(=O)N(C)C(=O)N2C"}` -> one classification object.
- Batch: `{"smiles": ["CCO", "c1ccccc1O"]}` -> `{"count": N, "results": [...]}`, one entry per input, same order. Prefer batches (up to 1000 SMILES) over many single calls.
- A bad SMILES in a batch gives that entry `{"smiles": ..., "error": {"code": "invalid_smiles", ...}}`; the rest still succeed. Always check each entry for an `error` key.
- Classification object fields: smiles, inchikey (always null), kingdom, superclass, class, subclass, intermediate_nodes, direct_parent, alternative_parents. Each node is `{"name": ..., "chemont_id": "CHEMONTID:0000247"}`; levels may be null.
- The usual answer to "what kind of compound is this?" is `direct_parent.name`; `class` and `superclass` give broader categories.

## Limits and errors

- Defaults: body 1 MiB, 1000 SMILES per request, 2000 characters per SMILES, 1000 atoms per molecule, 30 s per request. Live values: GET /version.
- Errors: `{"error": {"code": ..., "message": ...}}`; match on `code`. 503 `overloaded` -> wait about 1 s and retry. 504 `request_timeout` -> resend as smaller batches (no partial results are returned).
- Results depend on `rules_git_sha` from GET /version; store it alongside results.

## Example

```sh
curl -s https://HOST/classify -H 'Content-Type: application/json' -d '{"smiles": ["CCO", "CN1C=NC2=C1C(=O)N(C)C(=O)N2C"]}'
```

## Docs

- [OpenAPI 3.1 spec](/openapi.json): machine-readable schema for tool and function calling.
- [Homepage](/): human-readable documentation with a try-it box.
- [Version and limits](/version)