Skip to main content
The Bioptimus Model Server exposes a JSON REST API. The same ModelRequest / ModelResponse schema is used everywhere; what differs is how you reach it:
  • On-premise — path-based endpoints (/api/embed/h1, /api/predict/m-optimus, …) on the container (default port 8080). Interactive Swagger UI is served at /docs, and the live schema at /openapi.json.
  • AWS SageMaker — a single /invocations endpoint that accepts a SageMakerRequest (a ModelRequest plus model_name and mode for dispatch).
  • SDK — the Bioptimus SDK wraps both and is the recommended interface for whole-slide inference.
The model endpoints (embedding, prediction, metadata) are listed in the Endpoints section, generated from the server’s OpenAPI schema. The endpoints below are not part of that schema:
EndpointMethodPurpose
/invocationsPOSTSageMaker dispatch (adds model_name, mode)
/pingGETHealth check
/bioptimus/GETService discovery

​
Authentication

The Model Server REST API requires no authentication. Deploy it on a private network and restrict access at the network layer. On AWS, the SageMaker endpoint is protected by IAM (requests are SigV4-signed); on Hugging Face, model access is gated.

​
Errors

All endpoints return JSON. Common statuses:
StatusMeaning
200Success
422Validation error — malformed or missing fields (FastAPI HTTPValidationError)
500Inference error
503Model still loading, or GPU unavailable (see /ping states)
A 422 body follows the FastAPI shape: {"detail": [{"loc": [...], "msg": "...", "type": "..."}]}.