Skip to navigation
Reference

API Reference

View as Markdown

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:

FieldTypeRequiredDescription
atomsarrayYesList of AtomicData objects
opttolfloatNoPer-request force tolerance (eV/Å)
opttol_pressurefloatNoPer-request pressure tolerance (kBar)
celloptboolNoPer-request cell optimization flag
infostringNoOptional metadata to echo back

AtomicData Fields (atoms)

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

FieldTypeRequiredDescription
coordarray[float]YesFlattened coordinates [x1,y1,z1,x2,y2,z2,…] in Angstrom
numbersarray[int]YesAtomic numbers
cellarray[float]NoUnit cell (9 elements, row-major) in Angstrom
pbcarray[bool]NoPeriodic boundary conditions [x,y,z], default [true,true,true]
chargeintNoSystem charge, default 0
multintNoSpin multiplicity (2S+1), default 1
structure_idstringNoUnique identifier for tracking
active_maskarray[bool]NoMask for active atoms (true=optimize)

Response

The response contains the following fields:

FieldTypeDescription
atomsarrayList of OptimizationResult objects
statusstringStatus message (“Success” or error)
infostringEchoed metadata from request

OptimizationResult Fields (atoms items)

The following table lists the atoms items (OptimizationResult):

FieldTypeDescription
coordarray[float]Optimized coordinates in Angstrom
numbersarray[int]Atomic numbers
cellarray[float]Optimized unit cell (if cell optimization enabled)
pbcarray[bool]Periodic boundary conditions
energyfloatTotal energy in eV
forcesarray[float]Forces on atoms in eV/Å
stressarray[float]Stress tensor in kBar (if available)
chargesarray[float]Partial charges (if available)
convergedboolWhether optimization converged
optimizer_nstepsintNumber of optimization steps taken
structure_idstringEchoed structure identifier

Error Responses

The API returns the following error responses:

HTTP StatusMeaningWhen
200SuccessRequest completed. Check per-structure converged field for optimization status.
400Bad RequestMalformed JSON or missing required fields.
422Validation ErrorInvalid field types or values (for example, mismatched coord and numbers lengths, an empty atoms array, or structures with fewer than two atoms where unsupported).
500Internal Server ErrorUnexpected server failure or GPU out-of-memory (OOM) error.
503Service UnavailableNIM not ready (still estimating batch sizes at startup) or backend unavailable.

Error Response Schema (422)

{
  "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) might return 500 with an OOM error.
  • 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
}

GET /v1/health/live

Check if the Triton server is live.

Response

{
  "status": "live"
}

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
  }'