> ## 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.

# SageMaker dispatch endpoint

> SageMaker-compatible endpoint. Accepts a SageMakerRequest (ModelRequest plus `model_name` and `mode`) to route to the correct model and mode. Used by the SDK's AWS backend.



## OpenAPI

````yaml /api-reference/openapi.json post /invocations
openapi: 3.1.0
info:
  title: Bioptimus Model Server API
  version: 1.0.0
  description: >-
    REST API exposed by the Bioptimus Model Server. All model endpoints accept
    and return JSON; each request represents a single tile. The default port is
    8080. The server auto-batches concurrent tile requests for GPU efficiency
    (up to 32 tiles per forward pass by default).


    The same request/response schema is used on-premise (path-based endpoints
    below) and on AWS SageMaker (the `/invocations` dispatch endpoint). The
    `bioptimus` Python SDK wraps both — see the SDK guide.


    Authentication: the Model Server REST API currently requires no
    authentication. Secure it via network isolation / private networking. (Auth
    is being clarified.)
servers:
  - url: http://localhost:8080
    description: Local Bioptimus Model Server (replace host/port for your deployment)
security: []
tags:
  - name: Embedding
    description: Tile feature extraction
  - name: Prediction
    description: Spatial gene expression and tissue segmentation
  - name: Service
    description: Health and discovery
paths:
  /invocations:
    post:
      tags:
        - Service
      summary: SageMaker dispatch endpoint
      description: >-
        SageMaker-compatible endpoint. Accepts a SageMakerRequest (ModelRequest
        plus `model_name` and `mode`) to route to the correct model and mode.
        Used by the SDK's AWS backend.
      operationId: invocations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SageMakerRequest'
            example:
              model_name: h1
              mode: embedding
              image_data: <base64>
              slide_name: slide_A
              x: 0
              'y': 0
              width: 224
              height: 224
              patch_idx: 0
      responses:
        '200':
          description: Inference result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelResponse'
        '422':
          description: Validation error (malformed or missing fields)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Inference error
          content:
            application/json:
              example:
                detail: Internal server error
        '503':
          description: Model still loading or GPU unavailable
          content:
            application/json:
              example:
                status: loading
components:
  schemas:
    SageMakerRequest:
      allOf:
        - $ref: '#/components/schemas/ModelRequest'
        - type: object
          required:
            - model_name
            - mode
          properties:
            model_name:
              type: string
              enum:
                - h1
                - m-optimus
                - tissue-seg
              description: Target model.
            mode:
              type: string
              enum:
                - embedding
                - prediction
                - metadata
              description: Dispatch mode.
    ModelResponse:
      type: object
      properties:
        output:
          type: array
          items:
            type: number
          description: >-
            Model output vector: embeddings (1536), gene predictions, or a
            flattened mask.
        slide_name:
          type: string
        x:
          type: integer
        'y':
          type: integer
        width:
          type: integer
        height:
          type: integer
        tissue_ratio:
          type:
            - number
            - 'null'
        patch_idx:
          type: integer
        resolution:
          type:
            - number
            - 'null'
    HTTPValidationError:
      type: object
      properties:
        detail:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
    ModelRequest:
      type: object
      required:
        - image_data
        - slide_name
        - x
        - 'y'
        - width
        - height
        - patch_idx
      properties:
        image_data:
          type: string
          description: >-
            Base64-encoded PNG tile. (The SDK also accepts a PIL Image or raw
            bytes.)
        bulk_rna:
          type:
            - array
            - 'null'
          items:
            type: number
          default: null
          description: Optional bulk RNA counts vector (M-Optimus prediction only).
        slide_name:
          type: string
          description: Stem of the source slide filename.
        x:
          type: integer
          description: Tile x-coordinate in the slide.
        'y':
          type: integer
          description: Tile y-coordinate in the slide.
        width:
          type: integer
          description: Tile width in pixels.
        height:
          type: integer
          description: Tile height in pixels.
        tissue_ratio:
          type:
            - number
            - 'null'
          default: null
          description: Fraction of tissue in the tile.
        patch_idx:
          type: integer
          description: Index of this tile in the extraction plan.
        resolution:
          type:
            - number
            - 'null'
          default: null
          description: Extraction resolution in microns per pixel.
    ValidationError:
      type: object
      required:
        - loc
        - msg
        - type
      properties:
        loc:
          type: array
          items:
            anyOf:
              - type: string
              - type: integer
        msg:
          type: string
        type:
          type: string

````