> This page is for GenMol, version 2.0.0 (Latest) (default).
> For other versions, use one of these documentation indexes:
> - 2.0.0 (Latest) (default): https://docs.nvidia.com/nim/bionemo/genmol/2.0.0/llms.txt
> - 1.0.1: https://docs.nvidia.com/nim/bionemo/genmol/1.0.1/llms.txt
> - 1.0.0: https://docs.nvidia.com/nim/bionemo/genmol/1.0.0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nim/bionemo/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nim/bionemo/_mcp/server.

# Endpoints

## Molecular Generation

Endpoint path: `/generate`

### Input Parameters

* `smiles (string)`: Optional (default: null). SAFE or SMILES text with optional masks as the molecular template for generation. When null, performs de novo generation.
* `num_molecules (integer, 1~1000)`: Optional (default: 30). Maximum number of molecules to generate. The actual count returned may be lower since invalid generations are filtered out.
* `temperature (float, 0.01~10.0)`: Optional (default: 1.0). Temperature scaling factor for SoftMax sampling.
* `noise (float, 0.0~2.0)`: Optional (default: 1.0). Randomness factor used during diffusion sampling.
* `gamma (float, 0.0~1.0)`: Optional (default: 0.0). Classifier-free guidance strength. Set to 0 to disable.
* `min_add_len (integer, 1~128)`: Optional (default: 24). Minimum number of MASK tokens to add for generation.
* `step_size (integer, 1~10)`: Optional. Deprecated in v2.0.0 and accepted only for backward compatibility. The service ignores this field.
* `scoring (enum, QED or LogP)`: Optional (default: QED). Method used to score and rank generated molecules.
* `unique (boolean)`: Optional (default: false). When set, returns only unique molecules by removing duplicates.
* `filter (boolean)`: Optional (default: false). When enabled, removes generated molecules that do not contain the input fragment as a substructure (fragment-preservation validation). The default is false for backward compatibility. Enabling `filter` may reduce the number of returned molecules.

<Note>
Substructure-based validation is not fully reliable for all SAFE-based motif-extension inputs and should be treated as a mitigation, not a universal guarantee.
</Note>

### Outputs

The output is a JSON response with:

* `status`: `success` or `failed`
* `molecules`: On success, a list of generated molecules with `smiles` and `score`
* `error`: On failure, a short error message

### Example

```bash
curl --request POST --url "http://127.0.0.1:8000/generate" \
  --header "Content-Type: application/json" \
  --data '{
    "smiles": "[C@H]1O[C@@H](CO)[C@H](O)[C@@H]1O.[*{15-15}]",
    "num_molecules": 5,
    "temperature": 1.0,
    "noise": 1.0,
    "scoring": "QED"
  }'
```

```python
import json
import requests

session = requests.Session()
response = session.post(
    "http://127.0.0.1:8000/generate",
    headers={"Accept": "application/json"},
    json={
        "smiles": "[C@H]1O[C@@H](CO)[C@H](O)[C@@H]1O.[*{15-15}]",
        "num_molecules": 5,
        "temperature": 1.0,
        "noise": 1.0,
        "scoring": "QED",
    },
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))
```

### Example With Fragment Filtering

Use `filter: true` to retain only molecules that preserve the input fragment as a substructure. The returned count may be lower than `num_molecules` when filtering is active.

```bash
curl --request POST --url "http://127.0.0.1:8000/generate" \
  --header "Content-Type: application/json" \
  --data '{
    "smiles": "[C@H]1O[C@@H](CO)[C@H](O)[C@@H]1O.[*{15-15}]",
    "num_molecules": 10,
    "temperature": 1.0,
    "noise": 1.0,
    "scoring": "QED",
    "filter": true
  }'
```

```python
import json
import requests

session = requests.Session()
response = session.post(
    "http://127.0.0.1:8000/generate",
    headers={"Accept": "application/json"},
    json={
        "smiles": "[C@H]1O[C@@H](CO)[C@H](O)[C@@H]1O.[*{15-15}]",
        "num_molecules": 10,
        "temperature": 1.0,
        "noise": 1.0,
        "scoring": "QED",
        "filter": True,
    },
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))
```

## Readiness Check

Endpoint path: `/v1/health/ready`

### Example

```bash
curl http://127.0.0.1:8000/v1/health/ready
```

Example response:

```text
true
```

## List Models and Versions

Endpoint path: `/v1/models`

### Example

```bash
curl http://127.0.0.1:8000/v1/models
```

Example response:

```json
{"available_models":["GenMol-2.0.0"]}
```

## API Reference

Endpoint path: `/docs`

Open a web browser and navigate to `http://<host>:8000/docs` to view the generated OpenAPI reference page.

## Liveness and Metrics

For the liveness check (`/v1/health/live`) and runtime metrics (`/v1/metrics`), refer to [Observability](/nim/bionemo/genmol/observability).