{ "openapi": "3.2.0", "$self": "https://madeforagent.com/lmsp/1.0/openapi.json", "info": { "title": "Local Model Service Protocol (LMSP)", "summary": "An open protocol for discovering and calling language models that run on a user's own device.", "description": "LMSP 1.0, first public draft. This document is the machine-readable form of the specification at https://madeforagent.com/lmsp/1.0/. Where this document and the specification text differ, the text is normative.\n\nA service also offers an OpenAI-compatible interface under `/v1`. That interface follows OpenAI's own API reference and is not described here.\n", "version": "1.0.0-draft" }, "externalDocs": { "description": "The LMSP 1.0 specification", "url": "https://madeforagent.com/lmsp/1.0/" }, "servers": [ { "url": "http://127.0.0.1:17832", "description": "The default loopback address of an LMSP service" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Discovery", "description": "Finding a service and reading its capabilities." }, { "name": "Models", "description": "The catalog of local models and their lifecycle." }, { "name": "Responses", "description": "Synchronous and streaming generation." }, { "name": "Tasks", "description": "Asynchronous generation tasks that survive restarts." }, { "name": "Security", "description": "Pairing a client with a service." } ], "paths": { "/.well-known/lmsp.json": { "get": { "operationId": "getServiceDescription", "tags": [ "Discovery" ], "summary": "Get the service description", "description": "Service and capability discovery. Served without authentication.", "security": [], "responses": { "200": { "description": "The service description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceDescription" }, "examples": { "default": { "summary": "A service on the default address", "dataValue": { "protocol": "lmsp", "versions": [ "1.0" ], "service": { "id": "svc_01J8M4Y8K6M5E6K6Z7Z0Y8W3M2", "name": "Workstation Local Models", "version": "1.0.0" }, "interfaces": [ { "kind": "lmsp", "version": "1.0", "url": "http://127.0.0.1:17832/lmsp/v1", "transport": "http+json" }, { "kind": "openai", "version": "responses+chat", "url": "http://127.0.0.1:17832/v1", "transport": "http+json" } ], "capabilities": { "streaming": true, "tasks": true, "event_resume": true, "conversations": true, "model_management": true }, "authentication": { "type": "bearer", "pairing_url": "http://127.0.0.1:17832/lmsp/v1/pair" }, "openapi": "http://127.0.0.1:17832/lmsp/v1/openapi.json" } } } } } } } } }, "/lmsp/v1/openapi.json": { "get": { "operationId": "getOpenApiDocument", "tags": [ "Discovery" ], "summary": "Get the interface specification", "description": "Returns the OpenAPI document that describes the LMSP interface of this service. Served without authentication.", "security": [], "parameters": [ { "$ref": "#/components/parameters/LmspVersion" }, { "$ref": "#/components/parameters/LmspClient" } ], "responses": { "200": { "description": "An OpenAPI 3.2 document.", "content": { "application/json": { "schema": { "type": "object", "required": [ "openapi" ], "properties": { "openapi": { "type": "string" } } } } } } } } }, "/lmsp/v1/health": { "get": { "operationId": "getHealth", "tags": [ "Discovery" ], "summary": "Check liveness and readiness", "description": "Returns operational status only. It never contains model paths, prompts, access tokens or other sensitive information. Served without authentication.\n\nThe HTTP status is 200 when `status` is `ready` or `degraded`, and 503 otherwise.\n", "security": [], "parameters": [ { "$ref": "#/components/parameters/LmspVersion" }, { "$ref": "#/components/parameters/LmspClient" } ], "responses": { "200": { "description": "The service is ready, or degraded but still answering.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" }, "examples": { "default": { "summary": "A ready service", "dataValue": { "status": "ready", "service_id": "svc_01J8M4Y8K6M5E6K6Z7Z0Y8W3M2", "uptime_seconds": 86420, "loaded_models": 1, "active_tasks": 2, "storage": "ok" } } } } } }, "503": { "description": "The service is starting or stopping.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } } } } }, "/lmsp/v1/pair": { "post": { "operationId": "pairClient", "tags": [ "Security" ], "summary": "Exchange a pairing code for a bearer token", "description": "The user obtains a single-use pairing code from the service. The client submits it here and receives its own bearer token. Served without authentication.\n", "security": [], "parameters": [ { "$ref": "#/components/parameters/LmspVersion" }, { "$ref": "#/components/parameters/LmspClient" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PairRequest" }, "examples": { "default": { "summary": "Pair with the default scope", "dataValue": { "client_name": "example-client", "pairing_code": "K7QD-4M2X", "scopes": [ "inference" ] } } } } } }, "responses": { "200": { "description": "The client is paired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PairResponse" }, "examples": { "default": { "summary": "A new token", "dataValue": { "client_id": "cli_01J8MAT3W6X9B2D5F8H1K4N7QZ", "access_token": "lmsp_example_3f9a1c52e7d84b60", "token_type": "Bearer", "scopes": [ "inference" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/lmsp/v1/models": { "get": { "operationId": "listModels", "tags": [ "Models" ], "summary": "List local models", "description": "Returns the model catalog. The response carries `catalog_revision` and SHOULD carry an `ETag`, so clients can avoid fetching an unchanged catalog.\n", "parameters": [ { "$ref": "#/components/parameters/LmspVersion" }, { "$ref": "#/components/parameters/LmspClient" }, { "name": "capability", "in": "query", "required": false, "description": "Return only models that have this capability.", "schema": { "type": "string", "examples": [ "chat" ] } }, { "name": "ready_only", "in": "query", "required": false, "description": "When true, return only models whose status is `ready`.", "schema": { "type": "boolean", "default": false } }, { "name": "If-None-Match", "in": "header", "required": false, "description": "An earlier `ETag`. The service answers 304 if the catalog is unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The model catalog.", "headers": { "ETag": { "description": "A validator for the catalog.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelList" }, "examples": { "default": { "summary": "One ready model", "dataValue": { "object": "list", "catalog_revision": "42", "data": [ { "id": "qwen3:14b-q4_k_m", "object": "model", "display_name": "Qwen3 14B Q4_K_M", "owned_by": "local", "family": "qwen3", "revision": "sha256:8f27c1a4e9b05d36f2a7c8e1b4d90a63c5e2f7b8a1d4c9e60b3f5a7d2c8e1b04", "status": "ready", "capabilities": { "chat": true, "completion": true, "embeddings": false, "tools": true, "vision": false, "structured_output": true, "streaming": true }, "input_modalities": [ "text" ], "output_modalities": [ "text" ], "context_window": 32768, "max_output_tokens": 8192, "runtime": { "backend": "llama.cpp", "device": "metal", "load_on_demand": true } } ] } } } } } }, "304": { "description": "The catalog has not changed since the `ETag` the client sent." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/lmsp/v1/models/{model_id}": { "get": { "operationId": "getModel", "tags": [ "Models" ], "summary": "Get one model", "parameters": [ { "$ref": "#/components/parameters/LmspVersion" }, { "$ref": "#/components/parameters/LmspClient" }, { "$ref": "#/components/parameters/ModelId" } ], "responses": { "200": { "description": "The model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/lmsp/v1/models/{model_id}/load": { "post": { "operationId": "loadModel", "tags": [ "Models" ], "summary": "Preload a model", "description": "Optional. Available when the `model_management` capability is true. Requires the `models:manage` scope.\n", "parameters": [ { "$ref": "#/components/parameters/LmspVersion" }, { "$ref": "#/components/parameters/LmspClient" }, { "$ref": "#/components/parameters/ModelId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The model is already `ready`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" } } } }, "202": { "description": "Loading has started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "501": { "$ref": "#/components/responses/NotImplemented" } } } }, "/lmsp/v1/models/{model_id}/unload": { "post": { "operationId": "unloadModel", "tags": [ "Models" ], "summary": "Unload a model", "description": "Optional. Available when the `model_management` capability is true. Requires the `models:manage` scope. Repeating the request is harmless.\n", "parameters": [ { "$ref": "#/components/parameters/LmspVersion" }, { "$ref": "#/components/parameters/LmspClient" }, { "$ref": "#/components/parameters/ModelId" } ], "responses": { "200": { "description": "The model, after the unload was started or completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "501": { "$ref": "#/components/responses/NotImplemented" } } } }, "/lmsp/v1/responses": { "post": { "operationId": "createResponse", "tags": [ "Responses" ], "summary": "Generate a response", "description": "Synchronous generation, or a server-sent event stream when `stream` is true. A response streamed from this endpoint belongs to its HTTP connection and cannot be resumed. Use a task for resumable output.\n", "parameters": [ { "$ref": "#/components/parameters/LmspVersion" }, { "$ref": "#/components/parameters/LmspClient" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseRequest" }, "examples": { "default": { "summary": "A single-turn request", "dataValue": { "model": "qwen3:14b-q4_k_m", "input": [ { "type": "message", "role": "user", "content": [ { "type": "input_text", "text": "Describe a local model service in one sentence." } ] } ], "stream": false, "max_output_tokens": 512, "temperature": 0.7, "response_format": { "type": "text" }, "store": true } }, "tools": { "summary": "A request that offers a function tool", "dataValue": { "model": "qwen3:14b-q4_k_m", "input": [ { "type": "message", "role": "user", "content": [ { "type": "input_text", "text": "What is the weather in Hangzhou?" } ] } ], "tools": [ { "type": "function", "name": "get_weather", "description": "Get the current weather for a city.", "parameters": { "type": "object", "properties": { "city": { "type": "string" } }, "required": [ "city" ] } } ], "tool_choice": "auto" } } } } } }, "responses": { "200": { "description": "The finished response, or an event stream.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" }, "examples": { "default": { "summary": "A completed text response", "dataValue": { "id": "resp_01J8M6Q4W2T7N5R3V9X1Z8B0DF", "object": "response", "created_at": 1794200000, "status": "completed", "model": "qwen3:14b-q4_k_m", "output": [ { "id": "msg_01J8M6Q4W5C8H2K9P3S7Y1A6ZE", "type": "message", "role": "assistant", "content": [ { "type": "output_text", "text": "A local model service is a resident interface layer that discovers, manages and calls models on the user's own device." } ] } ], "usage": { "input_tokens": 28, "output_tokens": 31, "total_tokens": 59 }, "error": null, "incomplete_details": null } }, "tools": { "summary": "A response that calls a function", "dataValue": { "id": "resp_01J8M7B3N6Q9T2V5X8Z1C4D7FH", "object": "response", "created_at": 1794200050, "status": "completed", "model": "qwen3:14b-q4_k_m", "output": [ { "id": "fc_01J8M7B3N8R1S4W7Y0A3E6G9JK", "type": "function_call", "call_id": "call_01J8M7B3N9T2V5X8Z1C4D7F0HM", "name": "get_weather", "arguments": "{\"city\":\"Hangzhou\"}" } ], "usage": { "input_tokens": 74, "output_tokens": 18, "total_tokens": 92 }, "error": null, "incomplete_details": null } } } }, "text/event-stream": { "itemSchema": { "$ref": "#/components/schemas/ResponseEvent" }, "examples": { "default": { "summary": "A streamed text response", "serializedValue": "id: 1\nevent: response.created\ndata: {\"response_id\":\"resp_01J8M6Q4W2T7N5R3V9X1Z8B0DF\",\"status\":\"in_progress\"}\n\nid: 2\nevent: response.output_item.added\ndata: {\"response_id\":\"resp_01J8M6Q4W2T7N5R3V9X1Z8B0DF\",\"output_index\":0,\"item\":{\"id\":\"msg_01J8M6Q4W5C8H2K9P3S7Y1A6ZE\",\"type\":\"message\",\"role\":\"assistant\",\"content\":[]}}\n\nid: 3\nevent: response.output_text.delta\ndata: {\"response_id\":\"resp_01J8M6Q4W2T7N5R3V9X1Z8B0DF\",\"item_id\":\"msg_01J8M6Q4W5C8H2K9P3S7Y1A6ZE\",\"delta\":\"A local model \"}\n\nid: 4\nevent: response.output_text.delta\ndata: {\"response_id\":\"resp_01J8M6Q4W2T7N5R3V9X1Z8B0DF\",\"item_id\":\"msg_01J8M6Q4W5C8H2K9P3S7Y1A6ZE\",\"delta\":\"service is a resident interface layer.\"}\n\nid: 5\nevent: response.output_item.done\ndata: {\"response_id\":\"resp_01J8M6Q4W2T7N5R3V9X1Z8B0DF\",\"output_index\":0,\"item\":{\"id\":\"msg_01J8M6Q4W5C8H2K9P3S7Y1A6ZE\",\"type\":\"message\",\"role\":\"assistant\",\"content\":[{\"type\":\"output_text\",\"text\":\"A local model service is a resident interface layer.\"}]}}\n\nid: 6\nevent: response.completed\ndata: {\"response_id\":\"resp_01J8M6Q4W2T7N5R3V9X1Z8B0DF\",\"status\":\"completed\",\"usage\":{\"input_tokens\":28,\"output_tokens\":12,\"total_tokens\":40}}" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "426": { "$ref": "#/components/responses/UpgradeRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/lmsp/v1/responses/{response_id}": { "get": { "operationId": "getResponse", "tags": [ "Responses" ], "summary": "Retrieve a stored response", "description": "Optional. Available when the `conversations` capability is true. Returns a response that was stored with `store: true`.\n", "parameters": [ { "$ref": "#/components/parameters/LmspVersion" }, { "$ref": "#/components/parameters/LmspClient" }, { "name": "response_id", "in": "path", "required": true, "description": "The response id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The stored response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "501": { "$ref": "#/components/responses/NotImplemented" } } } }, "/lmsp/v1/tasks": { "post": { "operationId": "createTask", "tags": [ "Tasks" ], "summary": "Create an asynchronous generation task", "description": "The service persists the task before it answers `202 Accepted`.\n", "parameters": [ { "$ref": "#/components/parameters/LmspVersion" }, { "$ref": "#/components/parameters/LmspClient" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCreateRequest" }, "examples": { "default": { "summary": "A long report, failed on restart", "dataValue": { "type": "response", "input": { "model": "qwen3:14b-q4_k_m", "input": [ { "type": "message", "role": "user", "content": [ { "type": "input_text", "text": "Write a long report." } ] } ] }, "on_restart": "fail" } } } } } }, "responses": { "202": { "description": "The task was accepted and persisted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" }, "examples": { "default": { "summary": "A queued task", "dataValue": { "id": "task_01J8M8R5X3V7B2N4Q9T1W6Y0ZC", "object": "task", "type": "response", "status": "queued", "created_at": 1794200100, "updated_at": 1794200100, "response_id": "resp_01J8M8R5X4B9D2F6H1K3N7Q0ZW", "events_url": "/lmsp/v1/tasks/task_01J8M8R5X3V7B2N4Q9T1W6Y0ZC/events", "on_restart": "fail", "response": null, "error": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "426": { "$ref": "#/components/responses/UpgradeRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/lmsp/v1/tasks/{task_id}": { "get": { "operationId": "getTask", "tags": [ "Tasks" ], "summary": "Get an asynchronous task", "description": "Clients that do not use event streams poll this endpoint. The `response` field is set once the task has succeeded.\n", "parameters": [ { "$ref": "#/components/parameters/LmspVersion" }, { "$ref": "#/components/parameters/LmspClient" }, { "$ref": "#/components/parameters/TaskId" } ], "responses": { "200": { "description": "The task.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" }, "examples": { "default": { "summary": "A succeeded task", "dataValue": { "id": "task_01J8M8R5X3V7B2N4Q9T1W6Y0ZC", "object": "task", "type": "response", "status": "succeeded", "created_at": 1794200100, "updated_at": 1794200162, "response_id": "resp_01J8M8R5X4B9D2F6H1K3N7Q0ZW", "events_url": "/lmsp/v1/tasks/task_01J8M8R5X3V7B2N4Q9T1W6Y0ZC/events", "on_restart": "fail", "response": { "id": "resp_01J8M8R5X4B9D2F6H1K3N7Q0ZW", "object": "response", "created_at": 1794200100, "status": "completed", "model": "qwen3:14b-q4_k_m", "output": [ { "id": "msg_01J8M8R6A2C5E8G1J4M7P0S3VY", "type": "message", "role": "assistant", "content": [ { "type": "output_text", "text": "Local model services make on-device inference a shared, discoverable utility..." } ] } ], "usage": { "input_tokens": 12, "output_tokens": 1480, "total_tokens": 1492 }, "error": null, "incomplete_details": null }, "error": null } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/lmsp/v1/tasks/{task_id}/cancel": { "post": { "operationId": "cancelTask", "tags": [ "Tasks" ], "summary": "Cancel an asynchronous task", "description": "Idempotent. Cancelling a task that is already `cancelling` or `cancelled` returns the current task and no error. Cancelling a task that has already succeeded or failed is answered with `task_not_cancelable`.\n", "parameters": [ { "$ref": "#/components/parameters/LmspVersion" }, { "$ref": "#/components/parameters/LmspClient" }, { "$ref": "#/components/parameters/TaskId" } ], "responses": { "200": { "description": "The current task.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/lmsp/v1/tasks/{task_id}/events": { "get": { "operationId": "getTaskEvents", "tags": [ "Tasks" ], "summary": "Subscribe to or resume the event stream of a task", "description": "Optional. Available when the `event_resume` capability is true. The service replays only events whose sequence number is greater than `after`, or than `Last-Event-ID`. If both are present, `after` wins. Events older than the retention period give `event_history_expired`.\n", "parameters": [ { "$ref": "#/components/parameters/LmspVersion" }, { "$ref": "#/components/parameters/LmspClient" }, { "$ref": "#/components/parameters/TaskId" }, { "name": "after", "in": "query", "required": false, "description": "Replay only events with a sequence number greater than this value.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "Last-Event-ID", "in": "header", "required": false, "description": "The id of the last event the client received.", "schema": { "type": "string", "pattern": "^[0-9]+$" } } ], "responses": { "200": { "description": "A stream of response events for the response the task produces.", "content": { "text/event-stream": { "itemSchema": { "$ref": "#/components/schemas/ResponseEvent" }, "examples": { "default": { "summary": "The events of a short response", "serializedValue": "id: 1\nevent: response.created\ndata: {\"response_id\":\"resp_01J8M6Q4W2T7N5R3V9X1Z8B0DF\",\"status\":\"in_progress\"}\n\nid: 2\nevent: response.output_item.added\ndata: {\"response_id\":\"resp_01J8M6Q4W2T7N5R3V9X1Z8B0DF\",\"output_index\":0,\"item\":{\"id\":\"msg_01J8M6Q4W5C8H2K9P3S7Y1A6ZE\",\"type\":\"message\",\"role\":\"assistant\",\"content\":[]}}\n\nid: 3\nevent: response.output_text.delta\ndata: {\"response_id\":\"resp_01J8M6Q4W2T7N5R3V9X1Z8B0DF\",\"item_id\":\"msg_01J8M6Q4W5C8H2K9P3S7Y1A6ZE\",\"delta\":\"A local model \"}\n\nid: 4\nevent: response.output_text.delta\ndata: {\"response_id\":\"resp_01J8M6Q4W2T7N5R3V9X1Z8B0DF\",\"item_id\":\"msg_01J8M6Q4W5C8H2K9P3S7Y1A6ZE\",\"delta\":\"service is a resident interface layer.\"}\n\nid: 5\nevent: response.output_item.done\ndata: {\"response_id\":\"resp_01J8M6Q4W2T7N5R3V9X1Z8B0DF\",\"output_index\":0,\"item\":{\"id\":\"msg_01J8M6Q4W5C8H2K9P3S7Y1A6ZE\",\"type\":\"message\",\"role\":\"assistant\",\"content\":[{\"type\":\"output_text\",\"text\":\"A local model service is a resident interface layer.\"}]}}\n\nid: 6\nevent: response.completed\ndata: {\"response_id\":\"resp_01J8M6Q4W2T7N5R3V9X1Z8B0DF\",\"status\":\"completed\",\"usage\":{\"input_tokens\":28,\"output_tokens\":12,\"total_tokens\":40}}" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/Gone" }, "501": { "$ref": "#/components/responses/NotImplemented" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A token obtained through local pairing (`POST /lmsp/v1/pair`). Scopes: `inference`, `models:manage`, and the reserved `models:install` and `tools:execute`.\n" } }, "parameters": { "LmspVersion": { "name": "LMSP-Version", "in": "header", "required": false, "description": "The LMSP version the client targets, as `major.minor`.", "schema": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+$", "examples": [ "1.0" ] } }, "LmspClient": { "name": "LMSP-Client", "in": "header", "required": false, "description": "Identifies the client software, as `name/version`. For diagnostics only. It never changes protocol behavior.", "schema": { "type": "string", "examples": [ "example-client/1.2.0" ] } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A client-generated unique value of at most 255 characters. The same key with the same body returns the original result. The same key with a different body is answered with `idempotency_conflict`.\n", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, "ModelId": { "name": "model_id", "in": "path", "required": true, "description": "The model id, percent-encoded. `qwen3:14b-q4_k_m` is sent as `qwen3%3A14b-q4_k_m`.", "schema": { "type": "string" } }, "TaskId": { "name": "task_id", "in": "path", "required": true, "description": "The task id.", "schema": { "type": "string" } } }, "responses": { "BadRequest": { "description": "The request is malformed, or needs a capability that is not available (`invalid_request`, `context_length_exceeded`, `unsupported_capability`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Unauthorized": { "description": "The token is missing, invalid, expired or revoked, or a pairing code is wrong (`unauthorized`).", "headers": { "WWW-Authenticate": { "description": "Always `Bearer`.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Forbidden": { "description": "The token lacks the required scope, or the `Origin` or `Host` check failed (`forbidden`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "NotFound": { "description": "The model, response or task does not exist (`model_not_found`, `response_not_found`, `task_not_found`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "default": { "summary": "Unknown model", "dataValue": { "type": "urn:lmsp:error:model-not-found", "title": "Model not found", "status": 404, "code": "model_not_found", "detail": "No local model with id 'qwen3:14b-q4_k_m'", "request_id": "req_01J8M9S6Y4W8C3P5R1V7Z2A0DH", "retryable": false } } } } } }, "Conflict": { "description": "The request conflicts with the current state (`model_not_ready`, `task_not_cancelable`, `idempotency_conflict`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Gone": { "description": "The requested events are older than the retention period (`event_history_expired`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "UpgradeRequired": { "description": "The service does not support the requested major version (`unsupported_protocol_version`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "RateLimited": { "description": "Too many requests (`rate_limited`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "InternalError": { "description": "An unexpected failure inside the service, or loading a model failed (`internal_error`, `model_load_failed`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "NotImplemented": { "description": "The service does not implement this optional endpoint (`unsupported_capability`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Unavailable": { "description": "A resource or the backend is unavailable (`resource_exhausted`, `backend_unavailable`, `server_restarted`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "schemas": { "ServiceDescription": { "type": "object", "required": [ "protocol", "versions", "service", "interfaces", "capabilities", "authentication", "openapi" ], "properties": { "protocol": { "const": "lmsp" }, "versions": { "type": "array", "minItems": 1, "items": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+$" } }, "service": { "type": "object", "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string", "description": "A stable service identifier." }, "name": { "type": "string" }, "version": { "type": "string", "description": "The version of the service software." } } }, "interfaces": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceInterface" } }, "capabilities": { "$ref": "#/components/schemas/Capabilities" }, "authentication": { "type": "object", "required": [ "type", "pairing_url" ], "properties": { "type": { "const": "bearer" }, "pairing_url": { "type": "string", "format": "uri" } } }, "openapi": { "type": "string", "format": "uri" } } }, "ServiceInterface": { "type": "object", "required": [ "kind", "version", "url", "transport" ], "properties": { "kind": { "type": "string", "description": "`lmsp`, `openai` or `ollama`. Clients ignore kinds they do not know." }, "version": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "transport": { "type": "string", "examples": [ "http+json" ] } } }, "Capabilities": { "type": "object", "required": [ "streaming", "tasks" ], "properties": { "streaming": { "const": true, "description": "Responses can be streamed. Always true in 1.0." }, "tasks": { "const": true, "description": "Asynchronous tasks are available. Always true in 1.0." }, "event_resume": { "type": "boolean", "description": "Task event streams can be subscribed to and resumed." }, "conversations": { "type": "boolean", "description": "Responses can be stored, and `previous_response_id` works." }, "model_management": { "type": "boolean", "description": "Models can be loaded and unloaded explicitly." } } }, "Health": { "type": "object", "required": [ "status", "service_id", "uptime_seconds", "loaded_models", "active_tasks", "storage" ], "properties": { "status": { "enum": [ "starting", "ready", "degraded", "stopping" ] }, "service_id": { "type": "string" }, "uptime_seconds": { "type": "integer", "minimum": 0 }, "loaded_models": { "type": "integer", "minimum": 0 }, "active_tasks": { "type": "integer", "minimum": 0 }, "storage": { "enum": [ "ok", "error" ] } } }, "Scope": { "enum": [ "inference", "models:manage", "models:install", "tools:execute" ] }, "PairRequest": { "type": "object", "required": [ "client_name", "pairing_code" ], "properties": { "client_name": { "type": "string", "minLength": 1 }, "pairing_code": { "type": "string", "minLength": 1 }, "scopes": { "type": "array", "description": "Requested scopes. Defaults to `[\"inference\"]`.", "items": { "$ref": "#/components/schemas/Scope" } } } }, "PairResponse": { "type": "object", "required": [ "client_id", "access_token", "token_type", "scopes" ], "properties": { "client_id": { "type": "string" }, "access_token": { "type": "string" }, "token_type": { "const": "Bearer" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/Scope" } } } }, "ModelStatus": { "enum": [ "installed", "loading", "ready", "unloading", "error" ] }, "ModelCapabilities": { "type": "object", "description": "Boolean flags. A flag that is missing means false.", "properties": { "chat": { "type": "boolean" }, "completion": { "type": "boolean" }, "embeddings": { "type": "boolean" }, "tools": { "type": "boolean" }, "vision": { "type": "boolean" }, "structured_output": { "type": "boolean" }, "streaming": { "type": "boolean" } } }, "ModelRuntime": { "type": "object", "properties": { "backend": { "type": "string" }, "device": { "type": "string" }, "load_on_demand": { "type": "boolean" } } }, "Model": { "type": "object", "required": [ "id", "object", "display_name", "status", "capabilities" ], "properties": { "id": { "type": "string", "minLength": 1, "description": "A stable identifier. Display names and aliases are not keys." }, "object": { "const": "model" }, "display_name": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "owned_by": { "type": "string" }, "family": { "type": "string" }, "revision": { "type": "string", "description": "A digest of the model content, such as `sha256:8f27...`." }, "status": { "$ref": "#/components/schemas/ModelStatus" }, "capabilities": { "$ref": "#/components/schemas/ModelCapabilities" }, "input_modalities": { "type": "array", "items": { "type": "string" } }, "output_modalities": { "type": "array", "items": { "type": "string" } }, "context_window": { "type": "integer", "minimum": 1 }, "max_output_tokens": { "type": "integer", "minimum": 1 }, "runtime": { "$ref": "#/components/schemas/ModelRuntime" }, "error": { "$ref": "#/components/schemas/Problem" } } }, "ModelList": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "const": "list" }, "catalog_revision": { "type": "string", "description": "An opaque string that changes whenever the catalog changes." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } } } }, "InputTextPart": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "const": "input_text" }, "text": { "type": "string" } } }, "OutputTextPart": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "const": "output_text" }, "text": { "type": "string" } } }, "InputMessage": { "type": "object", "required": [ "type", "role", "content" ], "properties": { "type": { "const": "message" }, "role": { "enum": [ "system", "user", "assistant" ] }, "content": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/InputTextPart" }, { "$ref": "#/components/schemas/OutputTextPart" } ] } } } }, "FunctionCallItem": { "type": "object", "required": [ "type", "call_id", "name", "arguments" ], "properties": { "id": { "type": "string" }, "type": { "const": "function_call" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string", "contentMediaType": "application/json", "description": "The arguments, as a JSON-encoded string." } } }, "FunctionCallOutputItem": { "type": "object", "required": [ "type", "call_id", "output" ], "properties": { "type": { "const": "function_call_output" }, "call_id": { "type": "string" }, "output": { "type": "string", "description": "The result of the call, usually JSON-encoded." } } }, "InputItem": { "oneOf": [ { "$ref": "#/components/schemas/InputMessage" }, { "$ref": "#/components/schemas/FunctionCallItem" }, { "$ref": "#/components/schemas/FunctionCallOutputItem" } ], "discriminator": { "propertyName": "type", "mapping": { "message": "#/components/schemas/InputMessage", "function_call": "#/components/schemas/FunctionCallItem", "function_call_output": "#/components/schemas/FunctionCallOutputItem" } } }, "ResponseFormat": { "oneOf": [ { "type": "object", "required": [ "type" ], "properties": { "type": { "const": "text" } } }, { "type": "object", "required": [ "type", "json_schema" ], "properties": { "type": { "const": "json_schema" }, "json_schema": { "type": "object", "required": [ "name", "schema" ], "properties": { "name": { "type": "string" }, "schema": { "type": "object", "description": "A JSON Schema that the output must satisfy." }, "strict": { "type": "boolean" } } } } } ] }, "Tool": { "type": "object", "required": [ "type", "name" ], "properties": { "type": { "const": "function" }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "type": "object", "description": "A JSON Schema describing the arguments." } } }, "ToolChoice": { "oneOf": [ { "enum": [ "auto", "none", "required" ] }, { "type": "object", "required": [ "type", "name" ], "properties": { "type": { "const": "function" }, "name": { "type": "string" } } } ] }, "Extensions": { "type": "object", "description": "Private extensions, keyed by reverse-domain names.", "propertyNames": { "pattern": "^[a-z0-9-]+(\\.[a-z0-9-]+)+$" } }, "ResponseRequest": { "type": "object", "required": [ "model", "input" ], "properties": { "model": { "type": "string" }, "input": { "type": "array", "items": { "$ref": "#/components/schemas/InputItem" } }, "stream": { "type": "boolean", "default": false }, "max_output_tokens": { "type": "integer", "minimum": 1 }, "temperature": { "type": "number", "minimum": 0 }, "response_format": { "$ref": "#/components/schemas/ResponseFormat" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" } }, "tool_choice": { "$ref": "#/components/schemas/ToolChoice" }, "store": { "type": "boolean", "default": false, "description": "Ask the service to keep the response. Ignored without the `conversations` capability." }, "previous_response_id": { "type": "string", "description": "Continue from a stored response. Needs the `conversations` capability." }, "extensions": { "$ref": "#/components/schemas/Extensions" } } }, "ResponseStatus": { "enum": [ "in_progress", "completed", "incomplete", "failed", "cancelled" ] }, "Usage": { "type": "object", "required": [ "input_tokens", "output_tokens", "total_tokens" ], "properties": { "input_tokens": { "type": "integer", "minimum": 0 }, "output_tokens": { "type": "integer", "minimum": 0 }, "total_tokens": { "type": "integer", "minimum": 0 } } }, "IncompleteDetails": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string", "examples": [ "max_output_tokens" ] } } }, "OutputMessage": { "type": "object", "required": [ "id", "type", "role", "content" ], "properties": { "id": { "type": "string" }, "type": { "const": "message" }, "role": { "const": "assistant" }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/OutputTextPart" } } } }, "ReasoningItem": { "type": "object", "required": [ "id", "type", "summary" ], "properties": { "id": { "type": "string" }, "type": { "const": "reasoning" }, "summary": { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "const": "summary_text" }, "text": { "type": "string" } } } } } }, "OutputItem": { "oneOf": [ { "$ref": "#/components/schemas/OutputMessage" }, { "$ref": "#/components/schemas/FunctionCallItem" }, { "$ref": "#/components/schemas/ReasoningItem" } ], "discriminator": { "propertyName": "type", "mapping": { "message": "#/components/schemas/OutputMessage", "function_call": "#/components/schemas/FunctionCallItem", "reasoning": "#/components/schemas/ReasoningItem" } } }, "Response": { "type": "object", "required": [ "id", "object", "created_at", "status", "model", "output" ], "properties": { "id": { "type": "string" }, "object": { "const": "response" }, "created_at": { "type": "integer", "description": "Seconds since the Unix epoch." }, "status": { "$ref": "#/components/schemas/ResponseStatus" }, "model": { "type": "string" }, "output": { "type": "array", "items": { "$ref": "#/components/schemas/OutputItem" } }, "usage": { "$ref": "#/components/schemas/Usage" }, "error": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Problem" } ] }, "incomplete_details": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/IncompleteDetails" } ] } } }, "OnRestart": { "enum": [ "fail", "retry", "resume" ] }, "TaskStatus": { "enum": [ "queued", "loading", "running", "cancelling", "succeeded", "failed", "cancelled" ] }, "TaskCreateRequest": { "type": "object", "required": [ "type", "input" ], "properties": { "type": { "const": "response" }, "input": { "$ref": "#/components/schemas/ResponseRequest" }, "on_restart": { "allOf": [ { "$ref": "#/components/schemas/OnRestart" } ], "default": "fail" } } }, "Task": { "type": "object", "required": [ "id", "object", "type", "status", "created_at", "updated_at", "response_id", "on_restart" ], "properties": { "id": { "type": "string" }, "object": { "const": "task" }, "type": { "const": "response" }, "status": { "$ref": "#/components/schemas/TaskStatus" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "response_id": { "type": "string", "description": "The id of the response the task produces. Assigned when the task is created." }, "events_url": { "type": "string", "format": "uri-reference", "description": "Path of the event stream. Present when the `event_resume` capability is true." }, "on_restart": { "$ref": "#/components/schemas/OnRestart" }, "response": { "description": "The response once the task has succeeded, otherwise null.", "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Response" } ] }, "error": { "description": "A problem object when the task has failed, otherwise null.", "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Problem" } ] } } }, "ErrorCode": { "description": "The error codes defined by LMSP 1.0. A service MAY define further codes.", "enum": [ "invalid_request", "unauthorized", "forbidden", "model_not_found", "model_not_ready", "model_load_failed", "context_length_exceeded", "unsupported_capability", "unsupported_protocol_version", "response_not_found", "task_not_found", "task_not_cancelable", "idempotency_conflict", "event_history_expired", "rate_limited", "resource_exhausted", "backend_unavailable", "server_restarted", "internal_error" ] }, "Problem": { "type": "object", "description": "A problem document (RFC 9457) with LMSP members.", "required": [ "type", "title", "status", "code", "retryable" ], "properties": { "type": { "type": "string", "format": "uri", "description": "`urn:lmsp:error:` followed by the code with hyphens instead of underscores." }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": 100, "maximum": 599 }, "code": { "description": "A known error code, or a further code defined by the service. Clients handle unknown codes by `status` and `retryable`.", "anyOf": [ { "$ref": "#/components/schemas/ErrorCode" }, { "type": "string" } ] }, "detail": { "type": "string", "description": "Never contains secrets, prompts or generated content." }, "request_id": { "type": "string" }, "retryable": { "type": "boolean" } } }, "SseEvent": { "type": "object", "description": "The generic shape of a parsed `text/event-stream` event.", "required": [ "data" ], "properties": { "data": { "type": "string" }, "event": { "type": "string" }, "id": { "type": "string" }, "retry": { "type": "integer", "minimum": 0 } } }, "ResponseCreatedEventData": { "type": "object", "required": [ "response_id", "status" ], "properties": { "response_id": { "type": "string" }, "status": { "const": "in_progress" } } }, "OutputItemEventData": { "type": "object", "required": [ "response_id", "output_index", "item" ], "properties": { "response_id": { "type": "string" }, "output_index": { "type": "integer", "minimum": 0 }, "item": { "$ref": "#/components/schemas/OutputItem" } } }, "OutputTextDeltaEventData": { "type": "object", "required": [ "response_id", "item_id", "delta" ], "properties": { "response_id": { "type": "string" }, "item_id": { "type": "string" }, "delta": { "type": "string" } } }, "ResponseCompletedEventData": { "type": "object", "required": [ "response_id", "status" ], "properties": { "response_id": { "type": "string" }, "status": { "const": "completed" }, "usage": { "$ref": "#/components/schemas/Usage" } } }, "ResponseIncompleteEventData": { "type": "object", "required": [ "response_id", "status", "incomplete_details" ], "properties": { "response_id": { "type": "string" }, "status": { "const": "incomplete" }, "incomplete_details": { "$ref": "#/components/schemas/IncompleteDetails" }, "usage": { "$ref": "#/components/schemas/Usage" } } }, "ResponseFailedEventData": { "type": "object", "required": [ "response_id", "status", "error" ], "properties": { "response_id": { "type": "string" }, "status": { "const": "failed" }, "error": { "$ref": "#/components/schemas/Problem" } } }, "ResponseCancelledEventData": { "type": "object", "required": [ "response_id", "status" ], "properties": { "response_id": { "type": "string" }, "status": { "const": "cancelled" } } }, "ErrorEventData": { "type": "object", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/Problem" } } }, "ResponseEvent": { "description": "One event of a response stream. `id` is an integer sequence number, strictly increasing within the response and starting at 1. Services MAY send further events. Clients ignore event types they do not know.\n", "$ref": "#/components/schemas/SseEvent", "required": [ "event", "id" ], "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]*$" } }, "oneOf": [ { "title": "response.created", "properties": { "event": { "const": "response.created" }, "data": { "contentMediaType": "application/json", "contentSchema": { "$ref": "#/components/schemas/ResponseCreatedEventData" } } } }, { "title": "response.output_item.added", "properties": { "event": { "const": "response.output_item.added" }, "data": { "contentMediaType": "application/json", "contentSchema": { "$ref": "#/components/schemas/OutputItemEventData" } } } }, { "title": "response.output_text.delta", "properties": { "event": { "const": "response.output_text.delta" }, "data": { "contentMediaType": "application/json", "contentSchema": { "$ref": "#/components/schemas/OutputTextDeltaEventData" } } } }, { "title": "response.output_item.done", "properties": { "event": { "const": "response.output_item.done" }, "data": { "contentMediaType": "application/json", "contentSchema": { "$ref": "#/components/schemas/OutputItemEventData" } } } }, { "title": "response.completed", "properties": { "event": { "const": "response.completed" }, "data": { "contentMediaType": "application/json", "contentSchema": { "$ref": "#/components/schemas/ResponseCompletedEventData" } } } }, { "title": "response.incomplete", "properties": { "event": { "const": "response.incomplete" }, "data": { "contentMediaType": "application/json", "contentSchema": { "$ref": "#/components/schemas/ResponseIncompleteEventData" } } } }, { "title": "response.failed", "properties": { "event": { "const": "response.failed" }, "data": { "contentMediaType": "application/json", "contentSchema": { "$ref": "#/components/schemas/ResponseFailedEventData" } } } }, { "title": "response.cancelled", "properties": { "event": { "const": "response.cancelled" }, "data": { "contentMediaType": "application/json", "contentSchema": { "$ref": "#/components/schemas/ResponseCancelledEventData" } } } }, { "title": "error", "properties": { "event": { "const": "error" }, "data": { "contentMediaType": "application/json", "contentSchema": { "$ref": "#/components/schemas/ErrorEventData" } } } } ] } } } }