> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bioptimus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bioptimus Inference Server

> The REST API served by the Bioptimus Model Server, and the SageMaker dispatch endpoint.

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](/guides/get-started/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:

| Endpoint       | Method | Purpose                                        |
| -------------- | ------ | ---------------------------------------------- |
| `/invocations` | POST   | SageMaker dispatch (adds `model_name`, `mode`) |
| `/ping`        | GET    | Health check                                   |
| `/bioptimus/`  | GET    | Service 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:

| Status | Meaning                                                                        |
| ------ | ------------------------------------------------------------------------------ |
| `200`  | Success                                                                        |
| `422`  | Validation error — malformed or missing fields (FastAPI `HTTPValidationError`) |
| `500`  | Inference error                                                                |
| `503`  | Model still loading, or GPU unavailable (see `/ping` states)                   |

A `422` body follows the FastAPI shape: `{"detail": [{"loc": [...], "msg": "...", "type": "..."}]}`.