{ "components": { "schemas": { "AllItemsFailedResponse": { "properties": { "details": { "items": { "$ref": "#/components/schemas/InferenceErrorDetail" }, "type": "array" }, "error": { "type": "string" } }, "required": [ "error", "details" ], "type": "object" }, "AssignedWorker": { "properties": { "gpu": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" } }, "required": [ "name", "url", "gpu" ], "type": "object" }, "BundleConfigDocument": { "properties": { "adapters": { "items": { "type": "string" }, "type": "array" }, "name": { "type": "string" }, "priority": { "format": "int32", "type": "integer" }, "source": { "type": "string" } }, "required": [ "name", "priority", "source", "adapters" ], "type": "object" }, "BundleConfigSummary": { "properties": { "adapter_count": { "minimum": 0, "type": "integer" }, "bundle_id": { "type": "string" }, "connected_workers": { "minimum": 0, "type": "integer" }, "priority": { "format": "int32", "type": "integer" }, "source": { "type": "string" } }, "required": [ "bundle_id", "priority", "adapter_count", "source", "connected_workers" ], "type": "object" }, "BundleConfigsResponse": { "properties": { "bundles": { "items": { "$ref": "#/components/schemas/BundleConfigSummary" }, "type": "array" } }, "required": [ "bundles" ], "type": "object" }, "BundleConflictResponse": { "properties": { "detail": { "$ref": "#/components/schemas/BundleRoutingConflictDetail" } }, "required": [ "detail" ], "type": "object" }, "BundleRoutingConflictDetail": { "properties": { "code": { "type": "string" }, "compatible_bundles": { "items": { "type": "string" }, "type": "array" }, "message": { "type": "string" } }, "required": [ "code", "message", "compatible_bundles" ], "type": "object" }, "ClusterSummary": { "properties": { "gpu_count": { "format": "int32", "type": "integer" }, "models_loaded": { "format": "int32", "type": "integer" }, "total_qps": { "format": "double", "type": "number" }, "worker_count": { "format": "int32", "type": "integer" } }, "required": [ "worker_count", "gpu_count", "models_loaded", "total_qps" ], "type": "object" }, "ConfigModelDocument": { "properties": { "bundles": { "items": { "type": "string" }, "type": "array" }, "sie_id": { "type": "string" }, "source": { "type": "string" } }, "required": [ "sie_id", "source", "bundles" ], "type": "object" }, "ConfigModelSummary": { "properties": { "model_id": { "type": "string" }, "profiles": { "items": { "type": "string" }, "type": "array" }, "source": { "type": "string" } }, "required": [ "model_id", "profiles", "source" ], "type": "object" }, "ConfigModelsResponse": { "properties": { "models": { "items": { "$ref": "#/components/schemas/ConfigModelSummary" }, "type": "array" } }, "required": [ "models" ], "type": "object" }, "CreatePoolRequest": { "properties": { "bundle": { "type": [ "string", "null" ] }, "gpus": { "additionalProperties": { "format": "int32", "minimum": 0, "type": "integer" }, "minProperties": 1, "propertyNames": { "type": "string" }, "type": "object" }, "minimum_worker_count": { "format": "int32", "minimum": 0, "type": "integer" }, "name": { "type": "string" }, "ttl_seconds": { "format": "int64", "minimum": 0, "type": [ "integer", "null" ] } }, "required": [ "name", "gpus" ], "type": "object" }, "DenseVector": { "properties": { "dims": { "minimum": 0, "type": "integer" }, "dtype": { "$ref": "#/components/schemas/OutputDtype" }, "values": { "items": { "format": "float", "type": "number" }, "type": "array" } }, "required": [ "dims", "dtype", "values" ], "type": "object" }, "DocumentInput": { "properties": { "data": { "items": { "format": "int32", "minimum": 0, "type": "integer" }, "type": "array" }, "format": { "type": [ "string", "null" ] } }, "required": [ "data" ], "type": "object" }, "EncodeParams": { "properties": { "instruction": { "type": [ "string", "null" ] }, "options": {}, "output_dtype": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OutputDtype" } ] }, "output_types": { "items": { "$ref": "#/components/schemas/OutputType" }, "type": [ "array", "null" ] } }, "type": "object" }, "EncodeRequest": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ItemInput" }, "minItems": 1, "type": "array" }, "params": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EncodeParams" } ] } }, "required": [ "items" ], "type": "object" }, "EncodeResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/EncodeResult" }, "type": "array" }, "model": { "type": "string" }, "timing": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TimingInfo" } ] } }, "required": [ "model", "items" ], "type": "object" }, "EncodeResult": { "properties": { "dense": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DenseVector" } ] }, "id": { "type": [ "string", "null" ] }, "multivector": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MultiVector" } ] }, "sparse": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SparseVector" } ] } }, "type": "object" }, "Entity": { "properties": { "bbox": { "items": { "format": "double", "type": "number" }, "type": [ "array", "null" ] }, "end": { "minimum": 0, "type": [ "integer", "null" ] }, "label": { "type": "string" }, "score": { "format": "double", "type": "number" }, "start": { "minimum": 0, "type": [ "integer", "null" ] }, "text": { "type": "string" } }, "required": [ "text", "label", "score" ], "type": "object" }, "ErrorDetailCore": { "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "ExtractParams": { "properties": { "instruction": { "type": [ "string", "null" ] }, "labels": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "options": {}, "output_schema": {} }, "type": "object" }, "ExtractRequest": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ItemInput" }, "minItems": 1, "type": "array" }, "params": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ExtractParams" } ] } }, "required": [ "items" ], "type": "object" }, "ExtractResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ExtractResult" }, "type": "array" }, "model": { "type": "string" } }, "required": [ "model", "items" ], "type": "object" }, "ExtractResult": { "properties": { "classifications": { "items": {}, "type": "array" }, "data": {}, "entities": { "items": { "$ref": "#/components/schemas/Entity" }, "type": "array" }, "id": { "type": "string" }, "relations": { "items": { "$ref": "#/components/schemas/Relation" }, "type": "array" } }, "required": [ "id" ], "type": "object" }, "GatewayErrorResponse": { "properties": { "configured_gpu_types": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "details": { "items": { "$ref": "#/components/schemas/InferenceErrorDetail" }, "type": [ "array", "null" ] }, "error": {}, "gpu": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } }, "type": "object" }, "GatewayModelLoadFailedDetail": { "description": "SDK-style ``502`` body for ``MODEL_LOAD_FAILED`` (SDK short-circuit).", "properties": { "attempts": { "format": "int32", "type": "integer" }, "code": { "type": "string" }, "error_class": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "permanent": { "type": "boolean" } }, "required": [ "code", "message", "attempts", "permanent" ], "type": "object" }, "GatewayModelLoadFailedResponse": { "properties": { "error": { "$ref": "#/components/schemas/GatewayModelLoadFailedDetail" } }, "required": [ "error" ], "type": "object" }, "GpuNotConfiguredDetail": { "description": "``detail`` when the caller's ``X-SIE-MACHINE-PROFILE`` GPU is not in the gateway allow-list.", "properties": { "code": { "type": "string" }, "configured_gpu_types": { "items": { "type": "string" }, "type": "array" }, "gpu": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message", "gpu", "configured_gpu_types" ], "type": "object" }, "GpuNotConfiguredError": { "properties": { "detail": { "$ref": "#/components/schemas/GpuNotConfiguredDetail" } }, "required": [ "detail" ], "type": "object" }, "HealthResponse": { "properties": { "cluster": { "$ref": "#/components/schemas/ClusterSummary" }, "configured_gpu_types": { "items": { "type": "string" }, "type": "array" }, "live_gpu_types": { "items": { "type": "string" }, "type": "array" }, "models": { "items": { "$ref": "#/components/schemas/ModelInfo" }, "type": "array" }, "status": { "type": "string" }, "type": { "type": "string" }, "workers": { "items": { "$ref": "#/components/schemas/WorkerInfo" }, "type": "array" } }, "required": [ "status", "type", "configured_gpu_types", "live_gpu_types", "cluster", "workers", "models" ], "type": "object" }, "ImageInput": { "properties": { "data": { "items": { "format": "int32", "minimum": 0, "type": "integer" }, "type": "array" }, "format": { "type": [ "string", "null" ] } }, "required": [ "data" ], "type": "object" }, "InferenceErrorDetail": { "properties": { "code": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "item_index": { "format": "int32", "minimum": 0, "type": "integer" } }, "required": [ "item_index" ], "type": "object" }, "InferenceInternalServerErrorResponse": { "oneOf": [ { "$ref": "#/components/schemas/AllItemsFailedResponse" }, { "$ref": "#/components/schemas/StandardApiError" } ] }, "InferenceServiceUnavailableResponse": { "oneOf": [ { "$ref": "#/components/schemas/GatewayErrorResponse" }, { "$ref": "#/components/schemas/StandardApiError" }, { "$ref": "#/components/schemas/GpuNotConfiguredError" } ] }, "ItemInput": { "properties": { "document": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DocumentInput" } ] }, "id": { "type": [ "string", "null" ] }, "images": { "items": { "$ref": "#/components/schemas/ImageInput" }, "type": [ "array", "null" ] }, "metadata": {}, "text": { "type": [ "string", "null" ] } }, "type": "object" }, "MessageResponse": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" }, "ModelAckBundleStatus": { "properties": { "acked": { "type": "boolean" }, "acked_workers": { "items": { "type": "string" }, "type": "array" }, "bundle_id": { "type": "string" }, "expected_bundle_config_hash": { "type": "string" }, "pending_workers": { "items": { "type": "string" }, "type": "array" }, "total_eligible_workers": { "minimum": 0, "type": "integer" } }, "required": [ "bundle_id", "expected_bundle_config_hash", "total_eligible_workers", "acked_workers", "pending_workers", "acked" ], "type": "object" }, "ModelConfigStatusResponse": { "properties": { "all_bundles_acked": { "type": "boolean" }, "bundles": { "items": { "$ref": "#/components/schemas/ModelAckBundleStatus" }, "type": "array" }, "config_epoch": { "format": "int64", "minimum": 0, "type": "integer" }, "model_id": { "type": "string" }, "no_bundles": { "type": "boolean" }, "source": { "type": "string" } }, "required": [ "model_id", "config_epoch", "all_bundles_acked", "no_bundles", "bundles", "source" ], "type": "object" }, "ModelInfo": { "properties": { "gpu_types": { "items": { "type": "string" }, "type": "array" }, "name": { "type": "string" }, "state": { "type": "string" }, "total_queue_depth": { "format": "int32", "type": "integer" }, "worker_count": { "format": "int32", "type": "integer" } }, "required": [ "name", "state", "worker_count", "gpu_types", "total_queue_depth" ], "type": "object" }, "ModelInfoWire": { "description": "Wire shape aligned with ``sie_server`` ``ModelInfo`` for ``GET /v1/models``.", "properties": { "dims": { "additionalProperties": { "format": "int64", "type": "integer" }, "propertyNames": { "type": "string" }, "type": "object" }, "inputs": { "items": { "type": "string" }, "type": "array" }, "last_error": {}, "loaded": { "type": "boolean" }, "max_sequence_length": { "format": "int64", "minimum": 0, "type": [ "integer", "null" ] }, "name": { "type": "string" }, "outputs": { "items": { "type": "string" }, "type": "array" }, "profiles": { "additionalProperties": { "$ref": "#/components/schemas/ProfileInfoWire" }, "propertyNames": { "type": "string" }, "type": "object" }, "state": { "type": "string" } }, "required": [ "name", "inputs", "outputs", "dims", "loaded", "state", "profiles" ], "type": "object" }, "ModelNotFoundDetail": { "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "ModelNotFoundResponse": { "properties": { "detail": { "$ref": "#/components/schemas/ModelNotFoundDetail" } }, "required": [ "detail" ], "type": "object" }, "ModelsResponse": { "properties": { "models": { "items": { "$ref": "#/components/schemas/ModelInfoWire" }, "type": "array" } }, "required": [ "models" ], "type": "object" }, "MultiVector": { "properties": { "dtype": { "$ref": "#/components/schemas/OutputDtype" }, "num_tokens": { "minimum": 0, "type": "integer" }, "token_dims": { "minimum": 0, "type": "integer" }, "values": { "items": { "items": { "format": "float", "type": "number" }, "type": "array" }, "type": "array" } }, "required": [ "token_dims", "num_tokens", "dtype", "values" ], "type": "object" }, "OpenAIEmbeddingDataEntry": { "properties": { "embedding": { "$ref": "#/components/schemas/OpenAIEmbeddingVector" }, "index": { "minimum": 0, "type": "integer" }, "object": { "type": "string" } }, "required": [ "object", "embedding", "index" ], "type": "object" }, "OpenAIEmbeddingEncodingFormat": { "enum": [ "float", "base64" ], "type": "string" }, "OpenAIEmbeddingInput": { "oneOf": [ { "type": "string" }, { "items": { "type": "string" }, "type": "array" } ] }, "OpenAIEmbeddingRequest": { "description": "OpenAI-compatible ``POST /v1/embeddings`` request (subset supported on gateway).", "properties": { "dimensions": { "description": "Accepted but ignored; the gateway returns the model's native dimension.", "format": "int32", "minimum": 0, "type": [ "integer", "null" ] }, "encoding_format": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OpenAIEmbeddingEncodingFormat" } ] }, "input": { "$ref": "#/components/schemas/OpenAIEmbeddingInput" }, "model": { "type": "string" }, "user": { "description": "Accepted but ignored; kept for OpenAI SDK compatibility.", "type": [ "string", "null" ] } }, "required": [ "model", "input" ], "type": "object" }, "OpenAIEmbeddingUsage": { "properties": { "prompt_tokens": { "format": "int64", "minimum": 0, "type": "integer" }, "total_tokens": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "prompt_tokens", "total_tokens" ], "type": "object" }, "OpenAIEmbeddingVector": { "oneOf": [ { "items": { "format": "double", "type": "number" }, "type": "array" }, { "type": "string" } ] }, "OpenAIEmbeddingsListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/OpenAIEmbeddingDataEntry" }, "type": "array" }, "model": { "type": "string" }, "object": { "type": "string" }, "usage": { "$ref": "#/components/schemas/OpenAIEmbeddingUsage" } }, "required": [ "object", "data", "model", "usage" ], "type": "object" }, "OutputDtype": { "enum": [ "float32", "float16", "int8", "uint8", "binary" ], "type": "string" }, "OutputType": { "enum": [ "dense", "sparse", "multivector" ], "type": "string" }, "Pool": { "properties": { "spec": { "$ref": "#/components/schemas/PoolSpec" }, "status": { "$ref": "#/components/schemas/PoolStatus" } }, "required": [ "spec", "status" ], "type": "object" }, "PoolListResponse": { "properties": { "pools": { "items": { "$ref": "#/components/schemas/Pool" }, "type": "array" } }, "required": [ "pools" ], "type": "object" }, "PoolSpec": { "properties": { "bundle": { "type": [ "string", "null" ] }, "gpus": { "additionalProperties": { "format": "int32", "minimum": 0, "type": "integer" }, "propertyNames": { "type": "string" }, "type": "object" }, "minimum_worker_count": { "format": "int32", "minimum": 0, "type": "integer" }, "name": { "type": "string" }, "ttl_seconds": { "format": "int64", "minimum": 0, "type": [ "integer", "null" ] } }, "required": [ "name" ], "type": "object" }, "PoolState": { "enum": [ "pending", "active", "expired" ], "type": "string" }, "PoolStatus": { "properties": { "assigned_workers": { "items": { "$ref": "#/components/schemas/AssignedWorker" }, "type": "array" }, "created_at": { "format": "double", "type": "number" }, "last_renewed": { "format": "double", "type": "number" }, "state": { "$ref": "#/components/schemas/PoolState" } }, "required": [ "state" ], "type": "object" }, "ProfileInfoWire": { "properties": { "is_default": { "type": "boolean" } }, "type": "object" }, "ProvisioningResponse": { "properties": { "bundle": { "type": "string" }, "estimated_wait_s": { "format": "int64", "minimum": 0, "type": "integer" }, "gpu": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "string" } }, "required": [ "status", "estimated_wait_s" ], "type": "object" }, "Relation": { "properties": { "head": { "type": "string" }, "relation": { "type": "string" }, "score": { "format": "double", "type": "number" }, "tail": { "type": "string" } }, "required": [ "head", "tail", "relation", "score" ], "type": "object" }, "ResolveBundleConflictDetail": { "properties": { "bundle": { "type": "string" }, "code": { "type": "string" }, "compatible_bundles": { "items": { "type": "string" }, "type": "array" }, "message": { "type": "string" }, "model": { "type": "string" } }, "required": [ "code", "message", "model", "bundle", "compatible_bundles" ], "type": "object" }, "ResolveBundleConflictResponse": { "properties": { "detail": { "$ref": "#/components/schemas/ResolveBundleConflictDetail" } }, "required": [ "detail" ], "type": "object" }, "ResolveConfigResponse": { "properties": { "compatible_bundles": { "items": { "type": "string" }, "type": "array" }, "model": { "type": "string" }, "profiles": { "items": { "type": "string" }, "type": "array" }, "resolved_bundle": { "type": "string" } }, "required": [ "model", "resolved_bundle", "compatible_bundles", "profiles" ], "type": "object" }, "ResolveModelNotFoundDetail": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "model": { "type": "string" } }, "required": [ "code", "message", "model" ], "type": "object" }, "ResolveModelNotFoundResponse": { "properties": { "detail": { "$ref": "#/components/schemas/ResolveModelNotFoundDetail" } }, "required": [ "detail" ], "type": "object" }, "ResolveRequest": { "description": "POST /v1/configs/resolve - Resolve bundle for a model.", "properties": { "bundle": { "type": [ "string", "null" ] }, "model": { "type": "string" } }, "required": [ "model" ], "type": "object" }, "ScoreEntry": { "properties": { "item_id": { "type": "string" }, "rank": { "minimum": 0, "type": "integer" }, "score": { "format": "double", "type": "number" } }, "required": [ "item_id", "score", "rank" ], "type": "object" }, "ScoreRequest": { "properties": { "instruction": { "type": [ "string", "null" ] }, "items": { "items": { "$ref": "#/components/schemas/ItemInput" }, "minItems": 1, "type": "array" }, "options": {}, "query": { "$ref": "#/components/schemas/ItemInput" } }, "required": [ "query", "items" ], "type": "object" }, "ScoreResponse": { "properties": { "model": { "type": "string" }, "query_id": { "type": [ "string", "null" ] }, "scores": { "items": { "$ref": "#/components/schemas/ScoreEntry" }, "type": "array" } }, "required": [ "model", "scores" ], "type": "object" }, "SparseVector": { "properties": { "dims": { "minimum": 0, "type": [ "integer", "null" ] }, "dtype": { "$ref": "#/components/schemas/OutputDtype" }, "indices": { "items": { "minimum": 0, "type": "integer" }, "type": "array" }, "values": { "items": { "format": "float", "type": "number" }, "type": "array" } }, "required": [ "dtype", "indices", "values" ], "type": "object" }, "StandardApiError": { "description": "FastAPI-style error envelope for most gateway JSON errors.", "properties": { "detail": { "$ref": "#/components/schemas/ErrorDetailCore" } }, "required": [ "detail" ], "type": "object" }, "TimingInfo": { "properties": { "inference_ms": { "format": "double", "type": "number" }, "postprocessing_ms": { "format": "double", "type": [ "number", "null" ] }, "queue_ms": { "format": "double", "type": "number" }, "tokenization_ms": { "format": "double", "type": "number" }, "total_ms": { "format": "double", "type": "number" } }, "required": [ "total_ms", "queue_ms", "tokenization_ms", "inference_ms" ], "type": "object" }, "WorkerInfo": { "properties": { "bundle": { "type": "string" }, "bundle_config_hash": { "type": "string" }, "gpu": { "type": "string" }, "gpu_count": { "format": "int32", "type": "integer" }, "healthy": { "type": "boolean" }, "loaded_models": { "items": { "type": "string" }, "type": "array" }, "memory_total_bytes": { "format": "int64", "type": "integer" }, "memory_used_bytes": { "format": "int64", "type": "integer" }, "name": { "type": "string" }, "queue_depth": { "format": "int32", "type": "integer" }, "url": { "type": "string" } }, "required": [ "name", "url", "gpu", "gpu_count", "loaded_models", "queue_depth", "memory_used_bytes", "memory_total_bytes", "healthy", "bundle", "bundle_config_hash" ], "type": "object" } }, "securitySchemes": { "bearerAuth": { "bearerFormat": "opaque", "description": "SIE bearer token. Mutating pool/config/admin routes require the configured admin token; other protected routes accept a normal gateway token.", "scheme": "bearer", "type": "http" } } }, "info": { "description": "Rust gateway API for SIE inference, pool coordination, and read-only runtime config.", "license": { "name": "Apache-2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" }, "title": "SIE Gateway", "version": "0.3.2" }, "openapi": "3.1.0", "paths": { "/": { "get": { "operationId": "status_page", "responses": { "200": { "content": { "text/html": { "schema": { "type": "string" } } }, "description": "HTML gateway status page" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Missing or invalid bearer token (inference token)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Gateway auth enabled but no tokens configured" } }, "summary": "Static HTML status page", "tags": [ "health" ] } }, "/health": { "get": { "operationId": "health", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } }, "description": "Gateway cluster health" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Missing or invalid bearer token (inference token)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Gateway auth enabled but no tokens configured" } }, "tags": [ "health" ] } }, "/healthz": { "get": { "operationId": "healthz", "responses": { "200": { "content": { "text/plain; charset=utf-8": { "schema": { "type": "string" } } }, "description": "Liveness probe (plain text, matches sie_server)" } }, "security": [], "tags": [ "health" ] } }, "/metrics": { "get": { "operationId": "metrics_handler", "responses": { "200": { "content": { "text/plain": { "schema": { "type": "string" } } }, "description": "Prometheus metrics" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Missing or invalid bearer token (inference token)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Gateway auth enabled but no tokens configured" } }, "tags": [ "observability" ] } }, "/openapi.json": { "get": { "operationId": "openapi_json", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OpenAPI document" } }, "security": [], "tags": [ "docs" ] } }, "/readyz": { "get": { "description": "Process readiness only. Always returns 200 once the gateway is serving requests; never returns 503. Worker readiness is reported by GET /health and by inference responses (202 + Retry-After from a workerless gateway). This contract supports KEDA scale-from-zero.", "operationId": "readyz", "responses": { "200": { "content": { "text/plain; charset=utf-8": { "schema": { "type": "string" } } }, "description": "Gateway process is ready" } }, "security": [], "tags": [ "health" ] } }, "/v1/configs/bundles": { "get": { "operationId": "get_bundle_configs", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleConfigsResponse" } } }, "description": "Bundle configs visible to this gateway replica" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Missing or invalid bearer token (inference token)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Gateway auth enabled but no tokens configured" } }, "summary": "GET /v1/configs/bundles - List all bundle configs.", "tags": [ "config" ] } }, "/v1/configs/bundles/{id}": { "get": { "operationId": "get_bundle_config", "parameters": [ { "description": "Bundle id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/x-yaml": { "schema": { "$ref": "#/components/schemas/BundleConfigDocument" } } }, "description": "Bundle config YAML" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Missing or invalid bearer token (inference token)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Bundle not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Failed to serialize YAML; gateway auth enabled but no tokens configured" } }, "summary": "GET /v1/configs/bundles/{id} - Get specific bundle config.", "tags": [ "config" ] } }, "/v1/configs/models": { "get": { "operationId": "get_model_configs", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigModelsResponse" } } }, "description": "Model configs visible to this gateway replica" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Missing or invalid bearer token (inference token)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Gateway auth enabled but no tokens configured" } }, "summary": "GET /v1/configs/models - List all model configs visible to this gateway.", "tags": [ "config" ] } }, "/v1/configs/models/{id}": { "get": { "description": "Handles two endpoints sharing the same wildcard route:\n\n- `GET /v1/configs/models/{id}` — YAML view of the gateway's model.\n- `GET /v1/configs/models/{id}/status` — JSON worker-ack readiness for\n that model on this specific gateway replica.\n\nThe `{*id}` wildcard is necessary because model IDs routinely contain\nforward slashes (`BAAI/bge-m3`), so we strip an optional trailing\n`/status` segment here rather than maintain two overlapping axum routes\n(axum's `matchit` panics on overlapping catch-all routes).\n\nDisambiguation when a model literally named `something/status` exists:\nwe prefer the status interpretation only when the `/status`-stripped\nid resolves to a real model. That keeps an accidental model whose ID\nends with `/status` addressable under `GET\n/v1/configs/models/foo/status` as a config read, and matches what\nadmin tooling expects (status requests are only meaningful against\nmodels that actually exist). `sie-config` additionally refuses to\nregister model IDs ending in `/status` so the pathological case where\n**both** `foo` and `foo/status` are models cannot arise, but we\nstill degrade gracefully if it ever does.", "operationId": "get_model_config_or_status", "parameters": [ { "description": "Model id. Runtime route is Axum catch-all `/v1/configs/models/{*id}`; clients using this OpenAPI path template should percent-encode slashes in model ids, for example `BAAI%2Fbge-m3`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/x-yaml": { "schema": { "$ref": "#/components/schemas/ConfigModelDocument" } } }, "description": "Model config YAML" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Missing or invalid bearer token (inference token)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Model not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Failed to serialize YAML; gateway auth enabled but no tokens configured" } }, "summary": "GET /v1/configs/models/{*id} — dual-purpose dispatcher.", "tags": [ "config" ], "x-sie-axum-catch-all": "/v1/configs/models/{*id}" } }, "/v1/configs/models/{id}/status": { "get": { "operationId": "get_model_config_status", "parameters": [ { "description": "Model id. Runtime route is Axum catch-all `/v1/configs/models/{*id}`; clients using this OpenAPI path template should percent-encode slashes in model ids, for example `BAAI%2Fbge-m3`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelConfigStatusResponse" } } }, "description": "Per-replica worker acknowledgement status" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Missing or invalid bearer token (inference token)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Model not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Gateway auth enabled but no tokens configured" } }, "tags": [ "config" ], "x-sie-axum-catch-all": "/v1/configs/models/{*id}" } }, "/v1/configs/resolve": { "post": { "operationId": "resolve_config", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveConfigResponse" } } }, "description": "Resolved runtime bundle" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Missing or invalid bearer token (inference token)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Valid bearer token but admin token required for this mutation (or admin token not configured)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveModelNotFoundResponse" } } }, "description": "Model not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveBundleConflictResponse" } } }, "description": "Bundle override conflict" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Gateway auth enabled but no tokens configured" } }, "tags": [ "config" ] } }, "/v1/embeddings": { "post": { "description": "OpenAI-compatible embeddings proxy. A 200 response contains one embedding per input; partial or truncated internal encode success is treated as a 500 INTERNAL_ERROR instead of returning a partial 200.", "operationId": "proxy_openai_embeddings", "parameters": [ { "description": "Preferred GPU or machine profile", "in": "header", "name": "X-SIE-MACHINE-PROFILE", "required": false, "schema": { "type": [ "string", "null" ] } }, { "description": "Explicit pool routing override", "in": "header", "name": "X-SIE-Pool", "required": false, "schema": { "type": [ "string", "null" ] } }, { "description": "Client SDK version for skew warnings", "in": "header", "name": "X-SIE-SDK-Version", "required": false, "schema": { "type": [ "string", "null" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIEmbeddingRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIEmbeddingsListResponse" } } }, "description": "OpenAI-compatible embeddings response", "headers": { "X-Inference-Time": { "description": "Worker-reported inference time in milliseconds", "schema": { "type": "string" } }, "X-Payload-Fetch-Time": { "description": "Worker-reported offloaded payload fetch time in milliseconds, when available", "schema": { "type": "string" } }, "X-Postprocessing-Time": { "description": "Worker-reported postprocessing time in milliseconds, when available", "schema": { "type": "string" } }, "X-Queue-Publish-Time": { "description": "Milliseconds spent publishing work to the queue", "schema": { "type": "string" } }, "X-Queue-Time": { "description": "Worker-reported queue time in milliseconds", "schema": { "type": "string" } }, "X-Queue-Wait-Time": { "description": "Milliseconds spent waiting for worker results", "schema": { "type": "string" } }, "X-SIE-Request-Id": { "description": "Gateway request id for queue-backed inference", "schema": { "type": "string" } }, "X-SIE-Server-Version": { "description": "Gateway-compatible server version advertised by this gateway", "schema": { "type": "string" } }, "X-SIE-Version": { "description": "Gateway package version that handled the request", "schema": { "type": "string" } }, "X-SIE-Worker": { "description": "Logical queue worker tag that produced the response", "schema": { "type": "string" } }, "X-Tokenization-Time": { "description": "Worker-reported tokenization time in milliseconds, when available", "schema": { "type": "string" } } } }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisioningResponse" } } }, "description": "Worker provisioning in progress", "headers": { "Retry-After": { "description": "Suggested retry delay in seconds", "schema": { "type": "string" } }, "X-SIE-Server-Version": { "description": "Gateway-compatible server version advertised by this gateway", "schema": { "type": "string" } }, "X-SIE-Version": { "description": "Gateway package version that handled the request", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Missing or invalid bearer token" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Model not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleConflictResponse" } } }, "description": "Bundle override conflicts with model routing" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Request body too large" }, "500": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/InferenceInternalServerErrorResponse" }, { "$ref": "#/components/schemas/StandardApiError" } ] } } }, "description": "All batch items failed or gateway internal error; gateway auth enabled but no tokens configured" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayModelLoadFailedResponse" } } }, "description": "MODEL_LOAD_FAILED", "headers": { "X-SIE-Error-Code": { "description": "SDK-stable gateway or worker error code", "schema": { "type": "string" } }, "X-SIE-Error-Version": { "description": "Gateway package version associated with the error envelope", "schema": { "type": "string" } }, "X-SIE-Server-Version": { "description": "Gateway-compatible server version advertised by this gateway", "schema": { "type": "string" } }, "X-SIE-Version": { "description": "Gateway package version that handled the request", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InferenceServiceUnavailableResponse" } } }, "description": "Model loading, capacity, queue unavailable, or GPU not configured", "headers": { "Retry-After": { "description": "Suggested retry delay in seconds, when retryable", "schema": { "type": "string" } }, "X-SIE-Error-Code": { "description": "SDK-stable gateway or worker error code", "schema": { "type": "string" } }, "X-SIE-Server-Version": { "description": "Gateway-compatible server version advertised by this gateway", "schema": { "type": "string" } }, "X-SIE-Version": { "description": "Gateway package version that handled the request", "schema": { "type": "string" } } } }, "504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Result channel closed" } }, "tags": [ "inference" ] } }, "/v1/encode/{model}": { "post": { "description": "Mixed-success batches return 200 with only successful items; the response carries no per-item error envelope. For per-item error visibility, send single-item batches.", "operationId": "proxy_encode", "parameters": [ { "description": "Model id. Runtime route is Axum catch-all `/v1/encode/{*model}`; clients using this OpenAPI path template should percent-encode slashes in model ids, for example `BAAI%2Fbge-m3`.", "in": "path", "name": "model", "required": true, "schema": { "type": "string" } }, { "description": "Preferred GPU or machine profile", "in": "header", "name": "X-SIE-MACHINE-PROFILE", "required": false, "schema": { "type": [ "string", "null" ] } }, { "description": "Explicit pool routing override", "in": "header", "name": "X-SIE-Pool", "required": false, "schema": { "type": [ "string", "null" ] } }, { "description": "Client SDK version for skew warnings", "in": "header", "name": "X-SIE-SDK-Version", "required": false, "schema": { "type": [ "string", "null" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EncodeRequest" } }, "application/msgpack": { "schema": { "$ref": "#/components/schemas/EncodeRequest" } }, "application/vnd.msgpack": { "schema": { "$ref": "#/components/schemas/EncodeRequest" } }, "application/x-msgpack": { "schema": { "$ref": "#/components/schemas/EncodeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EncodeResponse" } }, "application/msgpack": { "schema": { "$ref": "#/components/schemas/EncodeResponse" } }, "application/vnd.msgpack": { "schema": { "$ref": "#/components/schemas/EncodeResponse" } }, "application/x-msgpack": { "schema": { "$ref": "#/components/schemas/EncodeResponse" } } }, "description": "Encode response", "headers": { "X-Inference-Time": { "description": "Worker-reported inference time in milliseconds", "schema": { "type": "string" } }, "X-Payload-Fetch-Time": { "description": "Worker-reported offloaded payload fetch time in milliseconds, when available", "schema": { "type": "string" } }, "X-Postprocessing-Time": { "description": "Worker-reported postprocessing time in milliseconds, when available", "schema": { "type": "string" } }, "X-Queue-Publish-Time": { "description": "Milliseconds spent publishing work to the queue", "schema": { "type": "string" } }, "X-Queue-Time": { "description": "Worker-reported queue time in milliseconds", "schema": { "type": "string" } }, "X-Queue-Wait-Time": { "description": "Milliseconds spent waiting for worker results", "schema": { "type": "string" } }, "X-SIE-Request-Id": { "description": "Gateway request id for queue-backed inference", "schema": { "type": "string" } }, "X-SIE-Server-Version": { "description": "Gateway-compatible server version advertised by this gateway", "schema": { "type": "string" } }, "X-SIE-Version": { "description": "Gateway package version that handled the request", "schema": { "type": "string" } }, "X-SIE-Worker": { "description": "Logical queue worker tag that produced the response", "schema": { "type": "string" } }, "X-Tokenization-Time": { "description": "Worker-reported tokenization time in milliseconds, when available", "schema": { "type": "string" } } } }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisioningResponse" } } }, "description": "Worker provisioning in progress", "headers": { "Retry-After": { "description": "Suggested retry delay in seconds", "schema": { "type": "string" } }, "X-SIE-Server-Version": { "description": "Gateway-compatible server version advertised by this gateway", "schema": { "type": "string" } }, "X-SIE-Version": { "description": "Gateway package version that handled the request", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Missing or invalid bearer token" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Model not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleConflictResponse" } } }, "description": "Bundle override conflicts with model routing" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Request body too large" }, "500": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/InferenceInternalServerErrorResponse" }, { "$ref": "#/components/schemas/StandardApiError" } ] } } }, "description": "All batch items failed or gateway internal error; gateway auth enabled but no tokens configured" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayModelLoadFailedResponse" } } }, "description": "Terminal model load failure (MODEL_LOAD_FAILED)", "headers": { "X-SIE-Error-Code": { "description": "SDK-stable gateway or worker error code", "schema": { "type": "string" } }, "X-SIE-Error-Version": { "description": "Gateway package version associated with the error envelope", "schema": { "type": "string" } }, "X-SIE-Server-Version": { "description": "Gateway-compatible server version advertised by this gateway", "schema": { "type": "string" } }, "X-SIE-Version": { "description": "Gateway package version that handled the request", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InferenceServiceUnavailableResponse" } } }, "description": "Queue unavailable, GPU not configured, model loading, or capacity exhausted", "headers": { "Retry-After": { "description": "Suggested retry delay in seconds, when retryable", "schema": { "type": "string" } }, "X-SIE-Error-Code": { "description": "SDK-stable gateway or worker error code", "schema": { "type": "string" } }, "X-SIE-Server-Version": { "description": "Gateway-compatible server version advertised by this gateway", "schema": { "type": "string" } }, "X-SIE-Version": { "description": "Gateway package version that handled the request", "schema": { "type": "string" } } } }, "504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Result channel closed" } }, "tags": [ "inference" ], "x-sie-axum-catch-all": "/v1/encode/{*model}" } }, "/v1/extract/{model}": { "post": { "description": "Mixed-success batches return 200 with only successful items; the response carries no per-item error envelope. For per-item error visibility, send single-item batches.", "operationId": "proxy_extract", "parameters": [ { "description": "Model id. Runtime route is Axum catch-all `/v1/extract/{*model}`; clients using this OpenAPI path template should percent-encode slashes in model ids, for example `BAAI%2Fbge-m3`.", "in": "path", "name": "model", "required": true, "schema": { "type": "string" } }, { "description": "Preferred GPU or machine profile", "in": "header", "name": "X-SIE-MACHINE-PROFILE", "required": false, "schema": { "type": [ "string", "null" ] } }, { "description": "Explicit pool routing override", "in": "header", "name": "X-SIE-Pool", "required": false, "schema": { "type": [ "string", "null" ] } }, { "description": "Client SDK version for skew warnings", "in": "header", "name": "X-SIE-SDK-Version", "required": false, "schema": { "type": [ "string", "null" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractRequest" } }, "application/msgpack": { "schema": { "$ref": "#/components/schemas/ExtractRequest" } }, "application/vnd.msgpack": { "schema": { "$ref": "#/components/schemas/ExtractRequest" } }, "application/x-msgpack": { "schema": { "$ref": "#/components/schemas/ExtractRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractResponse" } }, "application/msgpack": { "schema": { "$ref": "#/components/schemas/ExtractResponse" } }, "application/vnd.msgpack": { "schema": { "$ref": "#/components/schemas/ExtractResponse" } }, "application/x-msgpack": { "schema": { "$ref": "#/components/schemas/ExtractResponse" } } }, "description": "Extract response", "headers": { "X-Inference-Time": { "description": "Worker-reported inference time in milliseconds", "schema": { "type": "string" } }, "X-Payload-Fetch-Time": { "description": "Worker-reported offloaded payload fetch time in milliseconds, when available", "schema": { "type": "string" } }, "X-Postprocessing-Time": { "description": "Worker-reported postprocessing time in milliseconds, when available", "schema": { "type": "string" } }, "X-Queue-Publish-Time": { "description": "Milliseconds spent publishing work to the queue", "schema": { "type": "string" } }, "X-Queue-Time": { "description": "Worker-reported queue time in milliseconds", "schema": { "type": "string" } }, "X-Queue-Wait-Time": { "description": "Milliseconds spent waiting for worker results", "schema": { "type": "string" } }, "X-SIE-Request-Id": { "description": "Gateway request id for queue-backed inference", "schema": { "type": "string" } }, "X-SIE-Server-Version": { "description": "Gateway-compatible server version advertised by this gateway", "schema": { "type": "string" } }, "X-SIE-Version": { "description": "Gateway package version that handled the request", "schema": { "type": "string" } }, "X-SIE-Worker": { "description": "Logical queue worker tag that produced the response", "schema": { "type": "string" } }, "X-Tokenization-Time": { "description": "Worker-reported tokenization time in milliseconds, when available", "schema": { "type": "string" } } } }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisioningResponse" } } }, "description": "Worker provisioning in progress", "headers": { "Retry-After": { "description": "Suggested retry delay in seconds", "schema": { "type": "string" } }, "X-SIE-Server-Version": { "description": "Gateway-compatible server version advertised by this gateway", "schema": { "type": "string" } }, "X-SIE-Version": { "description": "Gateway package version that handled the request", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Missing or invalid bearer token" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Model not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleConflictResponse" } } }, "description": "Bundle override conflicts with model routing" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Request body too large" }, "500": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/InferenceInternalServerErrorResponse" }, { "$ref": "#/components/schemas/StandardApiError" } ] } } }, "description": "All batch items failed or gateway internal error; gateway auth enabled but no tokens configured" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayModelLoadFailedResponse" } } }, "description": "Terminal model load failure (MODEL_LOAD_FAILED)", "headers": { "X-SIE-Error-Code": { "description": "SDK-stable gateway or worker error code", "schema": { "type": "string" } }, "X-SIE-Error-Version": { "description": "Gateway package version associated with the error envelope", "schema": { "type": "string" } }, "X-SIE-Server-Version": { "description": "Gateway-compatible server version advertised by this gateway", "schema": { "type": "string" } }, "X-SIE-Version": { "description": "Gateway package version that handled the request", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InferenceServiceUnavailableResponse" } } }, "description": "Queue unavailable, GPU not configured, model loading, or capacity exhausted", "headers": { "Retry-After": { "description": "Suggested retry delay in seconds, when retryable", "schema": { "type": "string" } }, "X-SIE-Error-Code": { "description": "SDK-stable gateway or worker error code", "schema": { "type": "string" } }, "X-SIE-Server-Version": { "description": "Gateway-compatible server version advertised by this gateway", "schema": { "type": "string" } }, "X-SIE-Version": { "description": "Gateway package version that handled the request", "schema": { "type": "string" } } } }, "504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Result channel closed" } }, "tags": [ "inference" ], "x-sie-axum-catch-all": "/v1/extract/{*model}" } }, "/v1/models": { "get": { "operationId": "get_models", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelsResponse" } } }, "description": "Models visible to this gateway replica" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Missing or invalid bearer token (inference token)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Gateway auth enabled but no tokens configured" } }, "tags": [ "models" ] } }, "/v1/models/{model}": { "get": { "operationId": "get_model", "parameters": [ { "description": "Model id. Runtime route is Axum catch-all `/v1/models/{*model}`; clients using this OpenAPI path template should percent-encode slashes in model ids, for example `BAAI%2Fbge-m3`.", "in": "path", "name": "model", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelInfoWire" } } }, "description": "Model detail" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Missing or invalid bearer token (inference token)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelNotFoundResponse" } } }, "description": "Model not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Gateway auth enabled but no tokens configured" } }, "summary": "Detail counterpart to `get_models`.", "tags": [ "models" ], "x-sie-axum-catch-all": "/v1/models/{*model}" } }, "/v1/pools": { "get": { "operationId": "list_pools", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolListResponse" } } }, "description": "Pools visible to this gateway replica" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Missing or invalid bearer token (inference token)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Gateway auth enabled but no tokens configured" } }, "tags": [ "pools" ] }, "post": { "operationId": "create_pool", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePoolRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pool" } } }, "description": "Pool created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Invalid pool request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Missing or invalid bearer token (inference token)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Valid bearer token but admin token required for this mutation (or admin token not configured)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Gateway auth enabled but no tokens configured" } }, "tags": [ "pools" ] } }, "/v1/pools/{name}": { "delete": { "operationId": "delete_pool", "parameters": [ { "description": "Pool name", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } }, "description": "Pool deleted" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Missing or invalid bearer token (inference token)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Pool cannot be deleted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Pool not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Gateway auth enabled but no tokens configured" } }, "tags": [ "pools" ] }, "get": { "operationId": "get_pool", "parameters": [ { "description": "Pool name", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pool" } } }, "description": "Pool detail" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Missing or invalid bearer token (inference token)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Pool not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Gateway auth enabled but no tokens configured" } }, "tags": [ "pools" ] } }, "/v1/pools/{name}/renew": { "post": { "operationId": "renew_pool", "parameters": [ { "description": "Pool name", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } }, "description": "Pool renewed" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Missing or invalid bearer token (inference token)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Valid bearer token but admin token required for this mutation (or admin token not configured)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Pool not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Gateway auth enabled but no tokens configured" } }, "tags": [ "pools" ] } }, "/v1/score/{model}": { "post": { "description": "Mixed-success batches return 200 with only successful items; the response carries no per-item error envelope. For per-item error visibility, send single-item batches.", "operationId": "proxy_score", "parameters": [ { "description": "Model id. Runtime route is Axum catch-all `/v1/score/{*model}`; clients using this OpenAPI path template should percent-encode slashes in model ids, for example `BAAI%2Fbge-m3`.", "in": "path", "name": "model", "required": true, "schema": { "type": "string" } }, { "description": "Preferred GPU or machine profile", "in": "header", "name": "X-SIE-MACHINE-PROFILE", "required": false, "schema": { "type": [ "string", "null" ] } }, { "description": "Explicit pool routing override", "in": "header", "name": "X-SIE-Pool", "required": false, "schema": { "type": [ "string", "null" ] } }, { "description": "Client SDK version for skew warnings", "in": "header", "name": "X-SIE-SDK-Version", "required": false, "schema": { "type": [ "string", "null" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreRequest" } }, "application/msgpack": { "schema": { "$ref": "#/components/schemas/ScoreRequest" } }, "application/vnd.msgpack": { "schema": { "$ref": "#/components/schemas/ScoreRequest" } }, "application/x-msgpack": { "schema": { "$ref": "#/components/schemas/ScoreRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreResponse" } }, "application/msgpack": { "schema": { "$ref": "#/components/schemas/ScoreResponse" } }, "application/vnd.msgpack": { "schema": { "$ref": "#/components/schemas/ScoreResponse" } }, "application/x-msgpack": { "schema": { "$ref": "#/components/schemas/ScoreResponse" } } }, "description": "Score response", "headers": { "X-Inference-Time": { "description": "Worker-reported inference time in milliseconds", "schema": { "type": "string" } }, "X-Payload-Fetch-Time": { "description": "Worker-reported offloaded payload fetch time in milliseconds, when available", "schema": { "type": "string" } }, "X-Postprocessing-Time": { "description": "Worker-reported postprocessing time in milliseconds, when available", "schema": { "type": "string" } }, "X-Queue-Publish-Time": { "description": "Milliseconds spent publishing work to the queue", "schema": { "type": "string" } }, "X-Queue-Time": { "description": "Worker-reported queue time in milliseconds", "schema": { "type": "string" } }, "X-Queue-Wait-Time": { "description": "Milliseconds spent waiting for worker results", "schema": { "type": "string" } }, "X-SIE-Request-Id": { "description": "Gateway request id for queue-backed inference", "schema": { "type": "string" } }, "X-SIE-Server-Version": { "description": "Gateway-compatible server version advertised by this gateway", "schema": { "type": "string" } }, "X-SIE-Version": { "description": "Gateway package version that handled the request", "schema": { "type": "string" } }, "X-SIE-Worker": { "description": "Logical queue worker tag that produced the response", "schema": { "type": "string" } }, "X-Tokenization-Time": { "description": "Worker-reported tokenization time in milliseconds, when available", "schema": { "type": "string" } } } }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisioningResponse" } } }, "description": "Worker provisioning in progress", "headers": { "Retry-After": { "description": "Suggested retry delay in seconds", "schema": { "type": "string" } }, "X-SIE-Server-Version": { "description": "Gateway-compatible server version advertised by this gateway", "schema": { "type": "string" } }, "X-SIE-Version": { "description": "Gateway package version that handled the request", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Missing or invalid bearer token" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Model not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleConflictResponse" } } }, "description": "Bundle override conflicts with model routing" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Request body too large" }, "500": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/InferenceInternalServerErrorResponse" }, { "$ref": "#/components/schemas/StandardApiError" } ] } } }, "description": "All batch items failed or gateway internal error; gateway auth enabled but no tokens configured" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayModelLoadFailedResponse" } } }, "description": "Terminal model load failure (MODEL_LOAD_FAILED)", "headers": { "X-SIE-Error-Code": { "description": "SDK-stable gateway or worker error code", "schema": { "type": "string" } }, "X-SIE-Error-Version": { "description": "Gateway package version associated with the error envelope", "schema": { "type": "string" } }, "X-SIE-Server-Version": { "description": "Gateway-compatible server version advertised by this gateway", "schema": { "type": "string" } }, "X-SIE-Version": { "description": "Gateway package version that handled the request", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InferenceServiceUnavailableResponse" } } }, "description": "Queue unavailable, GPU not configured, model loading, or capacity exhausted", "headers": { "Retry-After": { "description": "Suggested retry delay in seconds, when retryable", "schema": { "type": "string" } }, "X-SIE-Error-Code": { "description": "SDK-stable gateway or worker error code", "schema": { "type": "string" } }, "X-SIE-Server-Version": { "description": "Gateway-compatible server version advertised by this gateway", "schema": { "type": "string" } }, "X-SIE-Version": { "description": "Gateway package version that handled the request", "schema": { "type": "string" } } } }, "504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Result channel closed" } }, "tags": [ "inference" ], "x-sie-axum-catch-all": "/v1/score/{*model}" } }, "/ws/cluster-status": { "get": { "operationId": "ws_cluster_status", "responses": { "101": { "description": "WebSocket cluster status stream" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Missing or invalid bearer token (inference token)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardApiError" } } }, "description": "Gateway auth enabled but no tokens configured" } }, "tags": [ "observability" ] } } }, "security": [ { "bearerAuth": [] } ], "tags": [ { "description": "Gateway health, readiness, and status surfaces", "name": "health" }, { "description": "Queue-backed inference entrypoints", "name": "inference" }, { "description": "Models visible to this gateway replica", "name": "models" }, { "description": "Runtime pool coordination", "name": "pools" }, { "description": "Read-only gateway view of model and bundle config", "name": "config" }, { "description": "Metrics and streaming status", "name": "observability" }, { "description": "API description", "name": "docs" } ] }