API Reference

OpenAPI Schema

The OpenAPI specification details the following endpoints:

• /v1/infer Inference endpoint for batched geometry relaxation
• /v1/health/live Health liveliness endpoint
• /v1/health/ready Health readiness endpoint
• /v1/status System status monitoring endpoint

For the full interactive schema, refer to the API Reference tab.

Endpoints

POST /v1/infer

Perform batched geometry relaxation on one or more atomic structures.

Request Body

The request body contains the following fields:

AtomicData Fields (atoms)

The following table lists the atoms field parameters (AtomicData):

When a unit cell is provided, its determinant must be positive and its volume must be greater than 1.0 ų.

Backend PBC mode is selected at container startup with ALCHEMI_NIM_PBC. The mode controls whether cell must be present; the nested pbc field controls which axes of that cell are periodic. To accept both cell-bearing and cell-free requests, run separate container instances with the corresponding backend modes.

Response

The response contains the following fields:

OptimizationResult Fields (atoms items)

The following table lists the atoms items (OptimizationResult):

Error Responses

The API returns the following error responses:

Example Validation Error (422)

The detail value is an array for request-schema errors, a string for the maximum-system-size check, or an object for service validation such as an invalid cell volume.

{
  "detail": [
    {
      "loc": ["body", "atoms", 0, "coord"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Timeout and Memory Behavior

• Requests with structures exceeding max_system_size (check by using GET /v1/status) return 422 before inference.
• There is no built-in server-side request timeout. Use client-side timeouts for large batches.
• Check the converged field in each result structure. A 200 response does not guarantee that all structures converged.

GET /v1/health/ready

Check if the NIM is ready to accept inference requests.

Response

{
  "status": "ready",
  "backends_alive": 2,
  "backends_total": 2
}

An HTTP 200 response reports "status":"ready" and includes both backend counts. If Triton is ready but no Alchemi backend worker responds, the endpoint returns HTTP 503 with "status":"no backends available", "backends_alive":0, and backends_total. Other HTTP 503 responses, such as Triton startup and health-check failures, contain only a status message.

GET /v1/health/live

Check if the Triton server is live.

Response

{
  "status": "live"
}

The endpoint returns 503 with {"status":"not live"} when the Triton inference server is not live. This check does not report the health of the Alchemi backend workers.

GET /v1/status

Get detailed system status including worker metrics.

Response

{
  "total": {
    "tasks_received": 100,
    "tasks_completed": 95,
    "queue_size_atoms": 1024,
    "queue_size_tasks": 5,
    "requests_received": 50,
    "requests_completed": 48,
    "requests_in_progress": 2,
    "max_system_size": 36876
  },
  "workers": [
    {
      "device": "cuda:0",
      "tasks_received": 50,
      "tasks_completed": 48,
      "queue_size_atoms": 512,
      "queue_size_tasks": 2,
      "batch_size": 36876,
      "max_batch_size": 47136,
      "gpu_model": "NVIDIA H100 80GB HBM3"
    }
  ]
}

Example Requests

The following sections show how to use the API to start an optimization request.

Single Structure Optimization

Start this request by running the following command:

curl -X 'POST' \
  'http://localhost:8000/v1/infer' \
  -H 'Content-Type: application/json' \
  -d '{
    "atoms": [{
      "coord": [0.0, 0.0, 0.0, 0.0, 0.0, 1.0],
      "numbers": [1, 1],
      "cell": [10, 0, 0, 0, 10, 0, 0, 0, 10]
    }]
  }'

Multiple Structures With Custom Tolerance

Start this request by running the following command:

curl -X 'POST' \
  'http://localhost:8000/v1/infer' \
  -H 'Content-Type: application/json' \
  -d '{
    "atoms": [
      {
        "coord": [0.0, 0.0, 0.0, 0.0, 0.0, 1.0],
        "numbers": [1, 1],
        "cell": [10, 0, 0, 0, 10, 0, 0, 0, 10],
        "structure_id": "H2_struct1"
      },
      {
        "coord": [0.0, 0.0, 0.0, 0.0, 0.0, 1.5],
        "numbers": [1, 1],
        "cell": [10, 0, 0, 0, 10, 0, 0, 0, 10],
        "structure_id": "H2_struct2"
      }
    ],
    "opttol": 0.001
  }'