University of Amsterdam Health API

openapi: 3.2.0
info:
  title: LiteLLM Health API
  description: "Enterprise Edition \n\nProxy Server to call 100+ LLMs in the OpenAI format. [**Customize Swagger Docs**](https://docs.litellm.ai/docs/proxy/enterprise#swagger-docs---custom-routes--branding)\n\n\U0001F449 [```LiteLLM Admin Panel on /ui```](/ui). Create, Edit Keys with SSO. Having issues? Try [```Fallback Login```](/fallback/login)\n\n\U0001F4B8 [```LiteLLM Model Cost Map```](https://models.litellm.ai/).\n\n\U0001F50E [```LiteLLM Model Hub```](/ui/model_hub_table). See available models on the proxy. [**Docs**](https://docs.litellm.ai/docs/proxy/ai_hub)"
  version: 1.95.0
  x-operator: institution
  x-provenance:
    method: probed
    source: https://llmproxy.uva.nl/openapi.json
    retrieved: '2026-08-19'
    note: Document is generated by the LiteLLM proxy software the University of Amsterdam self-hosts; the deployment, the key issuance and the host (llmproxy.uva.nl, UvA Azure) are the institution's. servers[] added by API Evangelist because the served document omits it; nothing else altered.
servers:
- url: https://llmproxy.uva.nl
  description: University of Amsterdam / Amsterdam University of Applied Sciences shared AI gateway
tags:
- name: health
paths:
  /test:
    get:
      tags:
      - health
      summary: Test Endpoint
      description: "[DEPRECATED] use `/health/liveliness` instead.\n\nA test endpoint that pings the proxy server to check if it's healthy.\n\nParameters:\n    request (Request): The incoming request.\n\nReturns:\n    dict: A dictionary containing the route of the request URL."
      operationId: test_endpoint_test_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - APIKeyHeader: []
  /health/services:
    get:
      tags:
      - health
      summary: Health Services Endpoint
      description: 'Use this admin-only endpoint to check if the service is healthy.


        Example:

        ```

        curl -L -X GET ''http://0.0.0.0:4000/health/services?service=datadog''     -H ''Authorization: Bearer sk-1234''

        ```'
      operationId: health_services_endpoint_health_services_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: service
        in: query
        required: true
        schema:
          anyOf:
          - enum:
            - slack_budget_alerts
            - langfuse
            - langfuse_otel
            - slack
            - openmeter
            - webhook
            - email
            - braintrust
            - datadog
            - datadog_llm_observability
            - generic_api
            - arize
            - galileo
            - newrelic
            - sqs
            type: string
          - type: string
          description: Specify the service being hit.
          title: Service
        description: Specify the service being hit.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /health:
    get:
      tags:
      - health
      summary: Health Endpoint
      description: "\U0001F6A8 USE `/health/liveliness` to health check the proxy \U0001F6A8\n\nSee more \U0001F449 https://docs.litellm.ai/docs/proxy/health\n\n\nCheck the health of all the endpoints in config.yaml\n\nTo run health checks in the background, add this to config.yaml:\n```\ngeneral_settings:\n    # ... other settings\n    background_health_checks: True\n```\nelse, the health checks will be run on models when /health is called.\n\nTo skip deployments that set ``model_info.disable_background_health_check: true``\non ``GET /health`` as well as in the background loop, set\n``general_settings.health_check_skip_disabled_background_models: true``."
      operationId: health_endpoint_health_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: model
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Specify the model name (optional)
          title: Model
        description: Specify the model name (optional)
      - name: model_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Specify the model ID (optional)
          title: Model Id
        description: Specify the model ID (optional)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /health/history:
    get:
      tags:
      - health
      summary: Health Check History Endpoint
      description: 'Get health check history for models


        Returns historical health check data with optional filtering.'
      operationId: health_check_history_endpoint_health_history_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: model
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by specific model name
          title: Model
        description: Filter by specific model name
      - name: status_filter
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by status (healthy/unhealthy)
          title: Status Filter
        description: Filter by status (healthy/unhealthy)
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          description: Number of records to return
          default: 100
          title: Limit
        description: Number of records to return
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Number of records to skip
          default: 0
          title: Offset
        description: Number of records to skip
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /health/latest:
    get:
      tags:
      - health
      summary: Latest Health Checks Endpoint
      description: 'Get the latest health check status for all models


        Returns the most recent health check result for each model.'
      operationId: latest_health_checks_endpoint_health_latest_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - APIKeyHeader: []
  /health/shared-status:
    get:
      tags:
      - health
      summary: Shared Health Check Status Endpoint
      description: 'Get the status of shared health check coordination across pods.


        Returns information about Redis connectivity, lock status, and cache status.'
      operationId: shared_health_check_status_endpoint_health_shared_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - APIKeyHeader: []
  /health/license:
    get:
      tags:
      - health
      summary: Health License Endpoint
      description: Return metadata about the configured LiteLLM license without exposing the key.
      operationId: health_license_endpoint_health_license_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - APIKeyHeader: []
  /active/callbacks:
    get:
      tags:
      - health
      summary: Active Callbacks
      description: "Returns a list of litellm level settings\n\nThis is useful for debugging and ensuring the proxy server is configured correctly.\n\nResponse schema:\n```\n{\n    \"alerting\": _alerting,\n    \"litellm.callbacks\": litellm_callbacks,\n    \"litellm.input_callback\": litellm_input_callbacks,\n    \"litellm.failure_callback\": litellm_failure_callbacks,\n    \"litellm.success_callback\": litellm_success_callbacks,\n    \"litellm._async_success_callback\": litellm_async_success_callbacks,\n    \"litellm._async_failure_callback\": litellm_async_failure_callbacks,\n    \"litellm._async_input_callback\": litellm_async_input_callbacks,\n    \"all_litellm_callbacks\": all_litellm_callbacks,\n    \"num_callbacks\": len(all_litellm_callbacks),\n    \"num_alerting\": _num_alerting,\n    \"litellm.request_timeout\": litellm.request_timeout,\n}\n```"
      operationId: active_callbacks_active_callbacks_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - APIKeyHeader: []
  /settings:
    get:
      tags:
      - health
      summary: Active Callbacks
      description: "Returns a list of litellm level settings\n\nThis is useful for debugging and ensuring the proxy server is configured correctly.\n\nResponse schema:\n```\n{\n    \"alerting\": _alerting,\n    \"litellm.callbacks\": litellm_callbacks,\n    \"litellm.input_callback\": litellm_input_callbacks,\n    \"litellm.failure_callback\": litellm_failure_callbacks,\n    \"litellm.success_callback\": litellm_success_callbacks,\n    \"litellm._async_success_callback\": litellm_async_success_callbacks,\n    \"litellm._async_failure_callback\": litellm_async_failure_callbacks,\n    \"litellm._async_input_callback\": litellm_async_input_callbacks,\n    \"all_litellm_callbacks\": all_litellm_callbacks,\n    \"num_callbacks\": len(all_litellm_callbacks),\n    \"num_alerting\": _num_alerting,\n    \"litellm.request_timeout\": litellm.request_timeout,\n}\n```"
      operationId: active_callbacks_settings_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - APIKeyHeader: []
  /health/readiness:
    get:
      tags:
      - health
      summary: Health Readiness
      description: 'Public readiness probe. Returns a low-detail payload safe to expose to

        unauthenticated load balancers — `status` plus `db` so orchestrators and

        external probes can distinguish "healthy" from "DB unreachable" without a

        credential. Admins can opt into the legacy detailed payload with

        general_settings.allow_public_health_readiness_details.'
      operationId: health_readiness_health_readiness_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
    options:
      tags:
      - health
      summary: Health Readiness Options
      description: Options endpoint for health/readiness check.
      operationId: health_readiness_options_health_readiness_options
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /health/readiness/details:
    get:
      tags:
      - health
      summary: Health Readiness Details
      description: Authenticated readiness diagnostics with DB/cache/callback metadata.
      operationId: health_readiness_details_health_readiness_details_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - APIKeyHeader: []
  /health/backlog:
    get:
      tags:
      - health
      summary: Health Backlog
      description: 'Returns the number of HTTP requests currently in-flight on this uvicorn worker.


        Use this to measure per-pod queue depth. A high value means the worker is

        processing many concurrent requests — requests arriving now will have to wait

        for the event loop to get to them, adding latency before LiteLLM even starts

        its own timer.'
      operationId: health_backlog_health_backlog_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - APIKeyHeader: []
  /health/drain:
    get:
      tags:
      - health
      summary: Health Drain
      description: "Graceful-drain probe for Kubernetes ``preStop`` hooks.\n\nDisabled by default and returns 404 unless ``general_settings`` sets\n``enable_drain_endpoint: true``. Calling it flips a process-wide\nshutting-down flag, so a successful call permanently takes the worker out\nof rotation until the pod restarts.\n\nBecause the kubelet calls preStop hooks without proxy credentials, the\nendpoint does not require ``user_api_key_auth``. To prevent any\npod-reachable caller from triggering shutdown, set\n``general_settings.drain_endpoint_token`` (or the ``DRAIN_ENDPOINT_TOKEN``\nenv var) and supply the same value on the ``X-Drain-Token`` header from\nthe preStop hook. Calls without the header (or with a wrong value) get a\n401 and have no side effect.\n\nWhen enabled, it marks the worker as shutting down (so /health/readiness\nand /health/liveliness immediately start returning 503, removing the pod\nfrom service) and blocks until the in-flight request counter drains to\nzero or ``GRACEFUL_SHUTDOWN_TIMEOUT`` elapses. Unlike a fixed ``sleep``,\nthis returns as soon as real in-flight work is done.\n\nWire it up as:\n\n```yaml\nlifecycle:\n  preStop:\n    httpGet:\n      path: /health/drain\n      port: 4000\n      httpHeaders:\n        - name: X-Drain-Token\n          value: <same value as drain_endpoint_token>\n```"
      operationId: health_drain_health_drain_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /health/liveness:
    get:
      tags:
      - health
      summary: Health Liveliness
      description: 'Unprotected endpoint for checking if worker is alive.


        Returns 503 once graceful shutdown has begun so Kubernetes stops counting

        the draining pod as live and terminates it on schedule.'
      operationId: health_liveliness_health_liveness_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
    options:
      tags:
      - health
      summary: Health Liveliness Options
      description: Options endpoint for health/liveliness check.
      operationId: health_liveliness_options_health_liveness_options
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /health/liveliness:
    get:
      tags:
      - health
      summary: Health Liveliness
      description: 'Unprotected endpoint for checking if worker is alive.


        Returns 503 once graceful shutdown has begun so Kubernetes stops counting

        the draining pod as live and terminates it on schedule.'
      operationId: health_liveliness_health_liveliness_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
    options:
      tags:
      - health
      summary: Health Liveliness Options
      description: Options endpoint for health/liveliness check.
      operationId: health_liveliness_options_health_liveliness_options
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /health/test_connection:
    post:
      tags:
      - health
      summary: Test Model Connection
      description: "Test a direct connection to a specific model.\n\nThis endpoint allows you to verify if your proxy can successfully connect to a specific model.\nIt's useful for troubleshooting model connectivity issues without going through the full proxy routing.\n\nExample:\n```bash\n# If model is configured in proxy_config.yaml, you only need to specify the model name:\ncurl -X POST 'http://localhost:4000/health/test_connection' \\\n  -H 'Authorization: Bearer sk-1234' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"litellm_params\": {\n        \"model\": \"gpt-4o\"\n    },\n    \"mode\": \"chat\"\n  }'\n\n# The endpoint will automatically use api_key, api_base, etc. from proxy_config.yaml\n\n# You can also override specific params or test with custom credentials:\ncurl -X POST 'http://localhost:4000/health/test_connection' \\\n  -H 'Authorization: Bearer sk-1234' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"litellm_params\": {\n        \"model\": \"azure/gpt-4o\",\n        \"api_key\": \"os.environ/AZURE_OPENAI_API_KEY\",\n        \"api_base\": \"os.environ/AZURE_OPENAI_ENDPOINT\",\n        \"api_version\": \"2024-10-21\"\n    },\n    \"mode\": \"chat\"\n  }'\n```\n\nNote: \n- If the model is configured in proxy_config.yaml, credentials (api_key, api_base, etc.) \n  will be automatically loaded from the config (with resolved environment variables).\n- You can override specific params by including them in the request.\n- You can use `os.environ/VARIABLE_NAME` syntax to reference environment variables,\n  which will be resolved automatically (same as in proxy_config.yaml).\n\nReturns:\n    dict: A dictionary containing the health check result with either success information or error details."
      operationId: test_model_connection_health_test_connection_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Body_test_model_connection_health_test_connection_post'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    Body_test_model_connection_health_test_connection_post:
      properties:
        mode:
          anyOf:
          - type: string
            enum:
            - chat
            - completion
            - embedding
            - audio_speech
            - audio_transcription
            - image_generation
            - video_generation
            - batch
            - rerank
            - realtime
            - responses
            - ocr
          - type: 'null'
          title: Mode
          description: The mode to test the model with. If not provided, auto-detected from model capabilities.
        litellm_params:
          additionalProperties: true
          type: object
          title: Litellm Params
          description: Parameters for litellm.completion, litellm.embedding for the health check
        model_info:
          additionalProperties: true
          type: object
          title: Model Info
          description: Model info for the health check
      type: object
      title: Body_test_model_connection_health_test_connection_post
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      description: Bearer token
      in: header
      name: x-litellm-api-key