{ "swagger": "2.0", "info": { "description": "llamactl is a control server for managing Llama Server instances.", "title": "llamactl API", "contact": {}, "license": { "name": "MIT License", "url": "https://opensource.org/license/mit/" }, "version": "1.0" }, "basePath": "/api/v1", "paths": { "/api/v1/auth/keys": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns a list of all API keys for the system user (excludes key hash and plain-text key)", "produces": [ "application/json" ], "tags": [ "Keys" ], "summary": "List all API keys", "responses": { "200": { "description": "List of API keys", "schema": { "type": "array", "items": { "$ref": "#/definitions/server.KeyResponse" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } }, "post": { "description": "Creates a new API key with the specified permissions and returns the plain-text key (only shown once)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Keys" ], "summary": "Create a new API key", "parameters": [ { "description": "API key configuration", "name": "key", "in": "body", "required": true, "schema": { "$ref": "#/definitions/server.CreateKeyRequest" } } ], "responses": { "201": { "description": "Created API key with plain-text key", "schema": { "$ref": "#/definitions/server.CreateKeyResponse" } }, "400": { "description": "Invalid request body or validation error", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/api/v1/auth/keys/{id}": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns details for a specific API key by ID (excludes key hash and plain-text key)", "produces": [ "application/json" ], "tags": [ "Keys" ], "summary": "Get details of a specific API key", "parameters": [ { "type": "integer", "description": "Key ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "API key details", "schema": { "$ref": "#/definitions/server.KeyResponse" } }, "400": { "description": "Invalid key ID", "schema": { "type": "string" } }, "404": { "description": "API key not found", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } }, "delete": { "security": [ { "ApiKeyAuth": [] } ], "description": "Deletes an API key by ID", "tags": [ "Keys" ], "summary": "Delete an API key", "parameters": [ { "type": "integer", "description": "Key ID", "name": "id", "in": "path", "required": true } ], "responses": { "204": { "description": "API key deleted successfully" }, "400": { "description": "Invalid key ID", "schema": { "type": "string" } }, "404": { "description": "API key not found", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/api/v1/auth/keys/{id}/permissions": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns the instance-level permissions for a specific API key (includes instance names)", "produces": [ "application/json" ], "tags": [ "Keys" ], "summary": "Get API key permissions", "parameters": [ { "type": "integer", "description": "Key ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "List of key permissions", "schema": { "type": "array", "items": { "$ref": "#/definitions/server.KeyPermissionResponse" } } }, "400": { "description": "Invalid key ID", "schema": { "type": "string" } }, "404": { "description": "API key not found", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/api/v1/auth/oidc/callback": { "get": { "description": "Handles the IdP redirect, verifies state and ID token, and establishes a session cookie", "produces": [ "text/html" ], "tags": [ "Auth" ], "summary": "Complete OIDC login", "responses": { "302": { "description": "Redirect to the WebUI root with an established session, or with ?auth_error=\u003cdenied|state|idp|exchange|token|groups\u003e on failure", "schema": { "type": "string" } } } } }, "/api/v1/auth/oidc/login": { "get": { "description": "Redirects the browser to the configured OpenID Connect provider to begin the login flow", "produces": [ "text/html" ], "tags": [ "Auth" ], "summary": "Start OIDC login", "responses": { "302": { "description": "Redirect to IdP", "schema": { "type": "string" } } } } }, "/api/v1/auth/oidc/logout": { "post": { "description": "Revokes the server-side session and clears the session cookie", "tags": [ "Auth" ], "summary": "End OIDC session", "responses": { "204": { "description": "Session terminated" } } } }, "/api/v1/auth/whoami": { "get": { "description": "Returns whether the caller has an OIDC session and whether OIDC login is configured. Intended for the WebUI bootstrap; never requires authentication.", "produces": [ "application/json" ], "tags": [ "Auth" ], "summary": "Get current authentication state", "responses": { "200": { "description": "Authentication state", "schema": { "$ref": "#/definitions/server.WhoamiResponse" } } } } }, "/api/v1/backends/llama-cpp/devices": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns a list of available devices for the llama server", "tags": [ "Backends" ], "summary": "List available devices for llama server", "responses": { "200": { "description": "List of devices", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/api/v1/backends/llama-cpp/help": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns the help text for the llama server command", "tags": [ "Backends" ], "summary": "Get help for llama server", "responses": { "200": { "description": "Help text", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/api/v1/backends/llama-cpp/parse-command": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Parses a llama-server command string into instance options", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Backends" ], "summary": "Parse llama-server command", "parameters": [ { "description": "Command to parse", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/server.ParseCommandRequest" } } ], "responses": { "200": { "description": "Parsed options", "schema": { "$ref": "#/definitions/instance.Options" } }, "400": { "description": "Invalid request or command", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/backends/llama-cpp/version": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns the version of the llama server command", "tags": [ "Backends" ], "summary": "Get version of llama server", "responses": { "200": { "description": "Version information", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/api/v1/backends/mlx/parse-command": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Parses MLX-LM server command string into instance options", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Backends" ], "summary": "Parse mlx_lm.server command", "parameters": [ { "description": "Command to parse", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/server.ParseCommandRequest" } } ], "responses": { "200": { "description": "Parsed options", "schema": { "$ref": "#/definitions/instance.Options" } }, "400": { "description": "Invalid request or command", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/backends/vllm/parse-command": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Parses a vLLM serve command string into instance options", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Backends" ], "summary": "Parse vllm serve command", "parameters": [ { "description": "Command to parse", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/server.ParseCommandRequest" } } ], "responses": { "200": { "description": "Parsed options", "schema": { "$ref": "#/definitions/instance.Options" } }, "400": { "description": "Invalid request or command", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/config": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns an allowlisted projection of the server configuration:\nglobal instance defaults, backend command/docker summaries, and\nthe local node name. Secret-bearing fields are never included.", "tags": [ "System" ], "summary": "Get server configuration", "responses": { "200": { "description": "Allowlisted configuration", "schema": { "$ref": "#/definitions/server.ConfigResponse" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/api/v1/instances": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns a list of all instances managed by the server", "tags": [ "Instances" ], "summary": "List all instances", "responses": { "200": { "description": "List of instances", "schema": { "type": "array", "items": { "$ref": "#/definitions/instance.Instance" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/api/v1/instances/{name}": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns the details of a specific instance by name. Returns\n404 when the instance does not exist locally or on its node.", "tags": [ "Instances" ], "summary": "Get details of a specific instance", "parameters": [ { "type": "string", "description": "Instance Name", "name": "name", "in": "path", "required": true } ], "responses": { "200": { "description": "Instance details", "schema": { "$ref": "#/definitions/instance.Instance" } }, "400": { "description": "Invalid name format", "schema": { "type": "string" } }, "404": { "description": "Instance does not exist", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } }, "put": { "security": [ { "ApiKeyAuth": [] } ], "description": "Updates the configuration of a specific instance by name", "consumes": [ "application/json" ], "tags": [ "Instances" ], "summary": "Update an instance's configuration", "parameters": [ { "type": "string", "description": "Instance Name", "name": "name", "in": "path", "required": true }, { "description": "Instance configuration options", "name": "options", "in": "body", "required": true, "schema": { "$ref": "#/definitions/instance.Options" } } ], "responses": { "200": { "description": "Updated instance details", "schema": { "$ref": "#/definitions/instance.Instance" } }, "400": { "description": "Invalid name format", "schema": { "type": "string" } }, "404": { "description": "Instance does not exist", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } }, "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Creates a new instance with the provided configuration options", "consumes": [ "application/json" ], "tags": [ "Instances" ], "summary": "Create and start a new instance", "parameters": [ { "type": "string", "description": "Instance Name", "name": "name", "in": "path", "required": true }, { "description": "Instance configuration options", "name": "options", "in": "body", "required": true, "schema": { "$ref": "#/definitions/instance.Options" } } ], "responses": { "201": { "description": "Created instance details", "schema": { "$ref": "#/definitions/instance.Instance" } }, "400": { "description": "Invalid request body", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } }, "delete": { "security": [ { "ApiKeyAuth": [] } ], "description": "Stops and removes a specific instance by name", "tags": [ "Instances" ], "summary": "Delete an instance", "parameters": [ { "type": "string", "description": "Instance Name", "name": "name", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid name format", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/api/v1/instances/{name}/logs": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns the logs from a specific instance by name with optional line limit", "tags": [ "Instances" ], "summary": "Get logs from a specific instance", "parameters": [ { "type": "string", "description": "Instance Name", "name": "name", "in": "path", "required": true }, { "type": "string", "description": "Number of lines to retrieve (default: all lines)", "name": "lines", "in": "query" } ], "responses": { "200": { "description": "Instance logs", "schema": { "type": "string" } }, "400": { "description": "Invalid name format or lines parameter", "schema": { "type": "string" } }, "404": { "description": "Instance does not exist", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/api/v1/instances/{name}/proxy": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Forwards HTTP requests to the llama-server instance running on a specific port", "tags": [ "Instances" ], "summary": "Proxy requests to a specific instance, does not autostart instance if stopped", "parameters": [ { "type": "string", "description": "Instance Name", "name": "name", "in": "path", "required": true } ], "responses": { "200": { "description": "Request successfully proxied to instance" }, "400": { "description": "Invalid name format", "schema": { "type": "string" } }, "404": { "description": "Instance does not exist", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } }, "503": { "description": "Instance is not running", "schema": { "type": "string" } } } }, "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Forwards HTTP requests to the llama-server instance running on a specific port", "tags": [ "Instances" ], "summary": "Proxy requests to a specific instance, does not autostart instance if stopped", "parameters": [ { "type": "string", "description": "Instance Name", "name": "name", "in": "path", "required": true } ], "responses": { "200": { "description": "Request successfully proxied to instance" }, "400": { "description": "Invalid name format", "schema": { "type": "string" } }, "404": { "description": "Instance does not exist", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } }, "503": { "description": "Instance is not running", "schema": { "type": "string" } } } } }, "/api/v1/instances/{name}/restart": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Restarts a specific instance by name", "tags": [ "Instances" ], "summary": "Restart a running instance", "parameters": [ { "type": "string", "description": "Instance Name", "name": "name", "in": "path", "required": true } ], "responses": { "200": { "description": "Restarted instance details", "schema": { "$ref": "#/definitions/instance.Instance" } }, "400": { "description": "Invalid name format", "schema": { "type": "string" } }, "404": { "description": "Instance does not exist", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/api/v1/instances/{name}/start": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Starts a specific instance by name", "tags": [ "Instances" ], "summary": "Start a stopped instance", "parameters": [ { "type": "string", "description": "Instance Name", "name": "name", "in": "path", "required": true } ], "responses": { "200": { "description": "Started instance details", "schema": { "$ref": "#/definitions/instance.Instance" } }, "400": { "description": "Invalid name format", "schema": { "type": "string" } }, "404": { "description": "Instance does not exist", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/api/v1/instances/{name}/stop": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Stops a specific instance by name", "tags": [ "Instances" ], "summary": "Stop a running instance", "parameters": [ { "type": "string", "description": "Instance Name", "name": "name", "in": "path", "required": true } ], "responses": { "200": { "description": "Stopped instance details", "schema": { "$ref": "#/definitions/instance.Instance" } }, "400": { "description": "Invalid name format", "schema": { "type": "string" } }, "404": { "description": "Instance does not exist", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/api/v1/llama-cpp/{name}/models": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns a list of models available in the specified llama.cpp instance", "tags": [ "Llama.cpp" ], "summary": "List models in a llama.cpp instance", "parameters": [ { "type": "string", "description": "Instance Name", "name": "name", "in": "path", "required": true } ], "responses": { "200": { "description": "Models list response", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid instance", "schema": { "type": "string" } }, "404": { "description": "Instance does not exist", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/api/v1/llama-cpp/{name}/models/{model}/load": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Loads the specified model in the given llama.cpp instance", "tags": [ "Llama.cpp" ], "summary": "Load a model in a llama.cpp instance", "parameters": [ { "type": "string", "description": "Instance Name", "name": "name", "in": "path", "required": true }, { "type": "string", "description": "Model Name", "name": "model", "in": "path", "required": true } ], "responses": { "200": { "description": "Success message", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Invalid request", "schema": { "type": "string" } }, "404": { "description": "Instance does not exist", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/api/v1/llama-cpp/{name}/models/{model}/unload": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Unloads the specified model in the given llama.cpp instance", "tags": [ "Llama.cpp" ], "summary": "Unload a model in a llama.cpp instance", "parameters": [ { "type": "string", "description": "Instance Name", "name": "name", "in": "path", "required": true }, { "type": "string", "description": "Model Name", "name": "model", "in": "path", "required": true } ], "responses": { "200": { "description": "Success message", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Invalid request", "schema": { "type": "string" } }, "404": { "description": "Instance does not exist", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/api/v1/models": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns a list of all models currently cached on the server. If node parameter is specified, only returns models from that node. If no node is specified, returns models from all nodes aggregated.", "produces": [ "application/json" ], "tags": [ "Models" ], "summary": "List cached models", "parameters": [ { "type": "string", "description": "Node name to query (if not specified, queries all nodes)", "name": "node", "in": "query" } ], "responses": { "200": { "description": "List of cached models from the specified node or aggregated from all nodes", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.CachedModel" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } }, "delete": { "security": [ { "ApiKeyAuth": [] } ], "description": "Deletes a cached model by its repository and optional tag", "tags": [ "Models" ], "summary": "Delete a cached model", "parameters": [ { "type": "string", "description": "Node name to forward the request to", "name": "node", "in": "query" }, { "type": "string", "description": "Repository", "name": "repo", "in": "query", "required": true }, { "type": "string", "description": "Tag", "name": "tag", "in": "query" } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "type": "string" } }, "404": { "description": "Model not found", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/api/v1/models/download": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Initiates the download of a model from a specified repository and tag. Returns a job ID to track progress.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Models" ], "summary": "Download a model from a repository", "parameters": [ { "type": "string", "description": "Node name to forward the request to", "name": "node", "in": "query" }, { "description": "Download request", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/server.DownloadRequest" } } ], "responses": { "202": { "description": "Download initiated", "schema": { "$ref": "#/definitions/server.DownloadResponse" } }, "400": { "description": "Invalid request", "schema": { "type": "string" } }, "404": { "description": "Node not found", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/api/v1/models/jobs": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns a list of all model download jobs with their details", "produces": [ "application/json" ], "tags": [ "Models" ], "summary": "List all model download jobs", "parameters": [ { "type": "string", "description": "Node name to forward the request to", "name": "node", "in": "query" } ], "responses": { "200": { "description": "List of jobs", "schema": { "$ref": "#/definitions/server.ListJobsResponse" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/api/v1/models/jobs/{id}": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns the details of a download job by its ID", "produces": [ "application/json" ], "tags": [ "Models" ], "summary": "Get details of a specific download job", "parameters": [ { "type": "string", "description": "Node name to forward the request to", "name": "node", "in": "query" }, { "type": "string", "description": "Job ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Job details", "schema": { "$ref": "#/definitions/server.JobResponse" } }, "400": { "description": "Invalid request", "schema": { "type": "string" } }, "404": { "description": "Job not found", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } }, "delete": { "security": [ { "ApiKeyAuth": [] } ], "description": "Cancels a model download job by its ID. Only jobs that are in progress can be cancelled.", "tags": [ "Models" ], "summary": "Cancel an ongoing model download job", "parameters": [ { "type": "string", "description": "Node name to forward the request to", "name": "node", "in": "query" }, { "type": "string", "description": "Job ID", "name": "id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "type": "string" } }, "404": { "description": "Job not found", "schema": { "type": "string" } }, "409": { "description": "Cannot delete job with current status", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/api/v1/nodes": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns a map of all nodes configured in the server (node name -\u003e node config)", "tags": [ "Nodes" ], "summary": "List all configured nodes", "responses": { "200": { "description": "Map of nodes", "schema": { "type": "object", "additionalProperties": { "$ref": "#/definitions/server.NodeResponse" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/api/v1/nodes/{name}": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns the details of a specific node by name", "tags": [ "Nodes" ], "summary": "Get details of a specific node", "parameters": [ { "type": "string", "description": "Node Name", "name": "name", "in": "path", "required": true } ], "responses": { "200": { "description": "Node details", "schema": { "$ref": "#/definitions/server.NodeResponse" } }, "400": { "description": "Invalid name format", "schema": { "type": "string" } }, "404": { "description": "Node not found", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/api/v1/nodes/{name}/health": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Local node is healthy by definition; remote nodes are pinged. Unreachable nodes get a 200 with status \"unreachable\", not an error.", "tags": [ "Nodes" ], "summary": "Check the health of a specific node", "parameters": [ { "type": "string", "description": "Node Name", "name": "name", "in": "path", "required": true } ], "responses": { "200": { "description": "Node health status", "schema": { "$ref": "#/definitions/server.NodeHealthResponse" } }, "400": { "description": "Invalid name format", "schema": { "type": "string" } }, "404": { "description": "Node not found", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/api/v1/version": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns the version of the llamactl command", "tags": [ "System" ], "summary": "Get llamactl version", "responses": { "200": { "description": "Version information", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/llama-cpp/{name}/": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Proxies requests to the llama.cpp UI for the specified instance", "produces": [ "text/html" ], "tags": [ "Llama.cpp" ], "summary": "Proxy requests to llama.cpp UI for the instance", "parameters": [ { "type": "string", "description": "Instance Name", "name": "name", "in": "query", "required": true } ], "responses": { "200": { "description": "Proxied HTML response", "schema": { "type": "string" } }, "400": { "description": "Invalid instance", "schema": { "type": "string" } }, "404": { "description": "Instance does not exist", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/llama-cpp/{name}/apply-template": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Proxies requests to the specified llama.cpp server instance, starting it on-demand if configured", "produces": [ "application/json" ], "tags": [ "Llama.cpp" ], "summary": "Proxy requests to llama.cpp server instance", "parameters": [ { "type": "string", "description": "Instance Name", "name": "name", "in": "path", "required": true } ], "responses": { "200": { "description": "Proxied response", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid instance", "schema": { "type": "string" } }, "404": { "description": "Instance does not exist", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/llama-cpp/{name}/completion": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Proxies requests to the specified llama.cpp server instance, starting it on-demand if configured", "produces": [ "application/json" ], "tags": [ "Llama.cpp" ], "summary": "Proxy requests to llama.cpp server instance", "parameters": [ { "type": "string", "description": "Instance Name", "name": "name", "in": "path", "required": true } ], "responses": { "200": { "description": "Proxied response", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid instance", "schema": { "type": "string" } }, "404": { "description": "Instance does not exist", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/llama-cpp/{name}/detokenize": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Proxies requests to the specified llama.cpp server instance, starting it on-demand if configured", "produces": [ "application/json" ], "tags": [ "Llama.cpp" ], "summary": "Proxy requests to llama.cpp server instance", "parameters": [ { "type": "string", "description": "Instance Name", "name": "name", "in": "path", "required": true } ], "responses": { "200": { "description": "Proxied response", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid instance", "schema": { "type": "string" } }, "404": { "description": "Instance does not exist", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/llama-cpp/{name}/embeddings": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Proxies requests to the specified llama.cpp server instance, starting it on-demand if configured", "produces": [ "application/json" ], "tags": [ "Llama.cpp" ], "summary": "Proxy requests to llama.cpp server instance", "parameters": [ { "type": "string", "description": "Instance Name", "name": "name", "in": "path", "required": true } ], "responses": { "200": { "description": "Proxied response", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid instance", "schema": { "type": "string" } }, "404": { "description": "Instance does not exist", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/llama-cpp/{name}/infill": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Proxies requests to the specified llama.cpp server instance, starting it on-demand if configured", "produces": [ "application/json" ], "tags": [ "Llama.cpp" ], "summary": "Proxy requests to llama.cpp server instance", "parameters": [ { "type": "string", "description": "Instance Name", "name": "name", "in": "path", "required": true } ], "responses": { "200": { "description": "Proxied response", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid instance", "schema": { "type": "string" } }, "404": { "description": "Instance does not exist", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/llama-cpp/{name}/metrics": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Proxies requests to the specified llama.cpp server instance, starting it on-demand if configured", "produces": [ "application/json" ], "tags": [ "Llama.cpp" ], "summary": "Proxy requests to llama.cpp server instance", "parameters": [ { "type": "string", "description": "Instance Name", "name": "name", "in": "path", "required": true } ], "responses": { "200": { "description": "Proxied response", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid instance", "schema": { "type": "string" } }, "404": { "description": "Instance does not exist", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/llama-cpp/{name}/props": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Proxies requests to the specified llama.cpp server instance, starting it on-demand if configured", "produces": [ "application/json" ], "tags": [ "Llama.cpp" ], "summary": "Proxy requests to llama.cpp server instance", "parameters": [ { "type": "string", "description": "Instance Name", "name": "name", "in": "path", "required": true } ], "responses": { "200": { "description": "Proxied response", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid instance", "schema": { "type": "string" } }, "404": { "description": "Instance does not exist", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } }, "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Proxies requests to the specified llama.cpp server instance, starting it on-demand if configured", "produces": [ "application/json" ], "tags": [ "Llama.cpp" ], "summary": "Proxy requests to llama.cpp server instance", "parameters": [ { "type": "string", "description": "Instance Name", "name": "name", "in": "path", "required": true } ], "responses": { "200": { "description": "Proxied response", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid instance", "schema": { "type": "string" } }, "404": { "description": "Instance does not exist", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/llama-cpp/{name}/reranking": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Proxies requests to the specified llama.cpp server instance, starting it on-demand if configured", "produces": [ "application/json" ], "tags": [ "Llama.cpp" ], "summary": "Proxy requests to llama.cpp server instance", "parameters": [ { "type": "string", "description": "Instance Name", "name": "name", "in": "path", "required": true } ], "responses": { "200": { "description": "Proxied response", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid instance", "schema": { "type": "string" } }, "404": { "description": "Instance does not exist", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/llama-cpp/{name}/slots": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Proxies requests to the specified llama.cpp server instance, starting it on-demand if configured", "produces": [ "application/json" ], "tags": [ "Llama.cpp" ], "summary": "Proxy requests to llama.cpp server instance", "parameters": [ { "type": "string", "description": "Instance Name", "name": "name", "in": "path", "required": true } ], "responses": { "200": { "description": "Proxied response", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid instance", "schema": { "type": "string" } }, "404": { "description": "Instance does not exist", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/llama-cpp/{name}/tokenize": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Proxies requests to the specified llama.cpp server instance, starting it on-demand if configured", "produces": [ "application/json" ], "tags": [ "Llama.cpp" ], "summary": "Proxy requests to llama.cpp server instance", "parameters": [ { "type": "string", "description": "Instance Name", "name": "name", "in": "path", "required": true } ], "responses": { "200": { "description": "Proxied response", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid instance", "schema": { "type": "string" } }, "404": { "description": "Instance does not exist", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/v1/": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Handles all POST requests to /v1/*, routing to the appropriate instance based on the request body. Requires API key authentication via the `Authorization` header.", "consumes": [ "application/json" ], "tags": [ "OpenAI" ], "summary": "OpenAI-compatible proxy endpoint", "responses": { "200": { "description": "OpenAI response" }, "400": { "description": "Invalid request body or instance name", "schema": { "type": "string" } }, "404": { "description": "Instance does not exist", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/v1/models": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns a list of instances in a format compatible with OpenAI API", "tags": [ "OpenAI" ], "summary": "List instances in OpenAI-compatible format", "responses": { "200": { "description": "List of OpenAI-compatible instances", "schema": { "$ref": "#/definitions/server.OpenAIListInstancesResponse" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } } }, "definitions": { "auth.PermissionMode": { "type": "string", "enum": [ "allow_all", "per_instance" ], "x-enum-varnames": [ "PermissionModeAllowAll", "PermissionModePerInstance" ] }, "instance.Instance": { "type": "object", "properties": { "created": { "description": "Unix timestamp when instance was created", "type": "integer" }, "id": { "type": "integer" }, "name": { "type": "string" } } }, "instance.Options": { "type": "object", "properties": { "auto_restart": { "description": "Auto restart", "type": "boolean" }, "command_override": { "type": "string" }, "docker_enabled": { "description": "Execution context overrides", "type": "boolean" }, "environment": { "description": "Environment variables", "type": "object", "additionalProperties": { "type": "string" } }, "group": { "description": "Instance group for hierarchical eviction", "type": "string" }, "idle_timeout": { "description": "Idle timeout", "type": "integer" }, "max_restarts": { "type": "integer" }, "on_demand_start": { "description": "On demand start", "type": "boolean" }, "preset_ini": { "description": "Preset configuration", "type": "string" }, "restart_delay": { "description": "seconds", "type": "integer" } } }, "models.CachedModel": { "type": "object", "properties": { "files": { "type": "array", "items": { "$ref": "#/definitions/models.File" } }, "node": { "type": "string" }, "repo": { "type": "string" }, "size_bytes": { "type": "integer" }, "tag": { "type": "string" } } }, "models.File": { "type": "object", "properties": { "name": { "type": "string" }, "path": { "type": "string" }, "size_bytes": { "type": "integer" }, "type": { "type": "string" } } }, "models.ModelFormat": { "type": "string", "enum": [ "gguf", "safetensors" ], "x-enum-varnames": [ "FormatGGUF", "FormatSafetensors" ] }, "models.Progress": { "type": "object", "properties": { "bytes_downloaded": { "type": "integer" }, "current_file": { "type": "string" }, "total_bytes": { "type": "integer" } } }, "server.BackendSummary": { "type": "object", "properties": { "command": { "type": "string" }, "docker": { "$ref": "#/definitions/server.DockerSummary" } } }, "server.Backends": { "type": "object", "properties": { "custom": { "type": "object", "additionalProperties": { "$ref": "#/definitions/server.BackendSummary" } }, "llama-cpp": { "$ref": "#/definitions/server.BackendSummary" }, "mlx": { "$ref": "#/definitions/server.BackendSummary" }, "vllm": { "$ref": "#/definitions/server.BackendSummary" } } }, "server.ConfigResponse": { "type": "object", "properties": { "backends": { "$ref": "#/definitions/server.Backends" }, "instance_defaults": { "$ref": "#/definitions/server.InstanceDefaults" }, "local_node": { "type": "string" } } }, "server.CreateKeyRequest": { "type": "object", "properties": { "expires_at": { "type": "integer" }, "name": { "type": "string" }, "permission_mode": { "$ref": "#/definitions/auth.PermissionMode" }, "permissions": { "type": "array", "items": { "$ref": "#/definitions/server.InstancePermissionSpec" } } } }, "server.CreateKeyResponse": { "type": "object", "properties": { "created_at": { "type": "integer" }, "expires_at": { "type": "integer" }, "id": { "type": "integer" }, "key": { "type": "string" }, "last_used_at": { "type": "integer" }, "name": { "type": "string" }, "permission_mode": { "$ref": "#/definitions/auth.PermissionMode" }, "updated_at": { "type": "integer" }, "user_id": { "type": "string" } } }, "server.DockerSummary": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "image": { "type": "string" } } }, "server.DownloadRequest": { "type": "object", "properties": { "format": { "$ref": "#/definitions/models.ModelFormat" }, "repo": { "type": "string" } } }, "server.DownloadResponse": { "type": "object", "properties": { "job_id": { "type": "string" }, "repo": { "type": "string" }, "tag": { "type": "string" } } }, "server.InstanceDefaults": { "type": "object", "properties": { "auto_restart": { "type": "boolean" }, "idle_timeout": { "type": "integer" }, "max_restarts": { "type": "integer" }, "on_demand_start": { "type": "boolean" }, "restart_delay": { "type": "integer" } } }, "server.InstancePermissionSpec": { "type": "object", "properties": { "can_evict": { "type": "boolean" }, "can_start": { "type": "boolean" }, "instance_id": { "type": "integer" } } }, "server.JobResponse": { "type": "object", "properties": { "completed_at": { "type": "integer" }, "created_at": { "type": "integer" }, "error": { "type": "string" }, "id": { "type": "string" }, "model_path": { "type": "string" }, "progress": { "$ref": "#/definitions/models.Progress" }, "repo": { "type": "string" }, "status": { "type": "string" }, "tag": { "type": "string" } } }, "server.KeyPermissionResponse": { "type": "object", "properties": { "can_evict": { "type": "boolean" }, "can_start": { "type": "boolean" }, "instance_id": { "type": "integer" }, "instance_name": { "type": "string" } } }, "server.KeyResponse": { "type": "object", "properties": { "created_at": { "type": "integer" }, "expires_at": { "type": "integer" }, "id": { "type": "integer" }, "last_used_at": { "type": "integer" }, "name": { "type": "string" }, "permission_mode": { "$ref": "#/definitions/auth.PermissionMode" }, "updated_at": { "type": "integer" }, "user_id": { "type": "string" } } }, "server.ListJobsResponse": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "$ref": "#/definitions/server.JobResponse" } } } }, "server.NodeHealthResponse": { "type": "object", "properties": { "checked_at": { "type": "integer" }, "error": { "type": "string" }, "latency_ms": { "description": "no omitempty: 0 is meaningful (local node, sub-ms ping)", "type": "integer" }, "status": { "$ref": "#/definitions/server.NodeHealthStatus" } } }, "server.NodeHealthStatus": { "type": "string", "enum": [ "healthy", "unreachable" ], "x-enum-varnames": [ "NodeStatusHealthy", "NodeStatusUnreachable" ] }, "server.NodeResponse": { "type": "object", "properties": { "address": { "type": "string" } } }, "server.OpenAIInstance": { "type": "object", "properties": { "created": { "type": "integer" }, "id": { "type": "string" }, "object": { "type": "string" }, "owned_by": { "type": "string" } } }, "server.OpenAIListInstancesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/server.OpenAIInstance" } }, "object": { "type": "string" } } }, "server.ParseCommandRequest": { "type": "object", "properties": { "command": { "type": "string" } } }, "server.WhoamiResponse": { "type": "object", "properties": { "authenticated": { "type": "boolean" }, "oidc_enabled": { "type": "boolean" }, "user": { "$ref": "#/definitions/server.WhoamiUser" } } }, "server.WhoamiUser": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" }, "sub": { "type": "string" } } } }, "securityDefinitions": { "ApiKeyAuth": { "type": "apiKey", "name": "X-API-Key", "in": "header" } } }