{ "openapi": "3.1.0", "info": { "title": "Msty Nexus API", "version": "current", "description": "Local API-first gateway and control plane for Msty Nexus. This contract describes the implemented early behavior: routes authenticate, provider and model records can be managed, provider credentials are stored behind credential references, and gateway inference routes can invoke configured OpenAI, Anthropic, OpenRouter, local OpenAI-compatible, Ollama, llama.cpp, and MLX adapters. JSON request bodies must contain exactly one JSON value; malformed JSON, unknown fields on typed writes, and trailing values return INVALID_JSON. Nexus generates X-Msty-Nexus-Request-Id for every response, sets OpenAI-compatible X-Request-Id and Anthropic-compatible request-id aliases, repeats the Nexus ID in error envelope request_id fields, and forwards it upstream as non-secret diagnostic context." }, "servers": [ { "url": "http://127.0.0.1:3939", "description": "Default local Msty Nexus server" } ], "security": [ { "bearerAuth": [] }, { "nexusTokenHeader": [] }, { "anthropicApiKey": [] } ], "paths": { "/health": { "get": { "summary": "Process health check", "security": [], "responses": { "200": { "description": "The local process is running.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" }, "examples": { "ok": { "value": { "status": "ok" } } } } } } } } }, "/version": { "get": { "summary": "Build and runtime version", "description": "Returns public build metadata for local launchers and supervisors. The response intentionally excludes tokens, provider credentials, paths, and local machine configuration.", "security": [], "responses": { "200": { "description": "Public build metadata for the running Nexus process.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionInfo" } } } } } } }, "/v1/settings": { "get": { "summary": "Get safe local settings", "description": "Returns token-protected operational settings for local launchers and UI clients. The response includes bind host, bind port, network exposure, effective CORS origins, runtime.modelsDirectory, runtime.tuning, usage posture, and the opt-in Gauge posture. It intentionally omits the local token, database path, runtime root, generated artifact paths, credential references, and provider credentials.", "responses": { "200": { "description": "Safe operational settings for the running Nexus process.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settings" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "patch": { "summary": "Update safe local settings", "description": "Updates durable local operator settings for local launchers and UI clients. bind.networkExposed persists a safe local-only versus network-exposed listener choice and is reported as pending until Nexus Runtime restarts; callers cannot supply arbitrary bind hosts or ports. cors.allowedOrigins updates origin access immediately. runtime.modelsDirectory changes the single local models root used for Nexus-managed model storage. runtime.tuning changes local runtime resource behavior and uses 0 for automatic defaults. gauge.enabled opts into the dedicated Gauge feature and gauge.retentionDays controls normalized history retention. Runtime roots, artifact paths, local tokens, database paths, credential references, and provider credentials are intentionally outside this mutation contract.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingsPatch" }, "examples": { "exposeRuntimeOnNetwork": { "value": { "bind": { "networkExposed": true } } }, "returnRuntimeToLocalOnly": { "value": { "bind": { "networkExposed": false } } }, "enableLocalBrowserClient": { "value": { "cors": { "allowedOrigins": [ "http://localhost:3000" ] } } }, "disableBrowserClients": { "value": { "cors": { "allowedOrigins": [] } } } } } } }, "responses": { "200": { "description": "Updated effective settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settings" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/gauge": { "get": { "summary": "Get the Gauge dashboard", "description": "Returns the opt-in cross-provider Gauge dashboard with redacted source status, normalized quota windows, spend, usage, source reachability, forecasts, and bounded compact history. Credential values, credential references, provider response bodies, and local credential paths are never returned.", "parameters": [ { "name": "since", "in": "query", "description": "Optional RFC3339 lower bound for compact hourly dashboard history. Defaults to the trailing 30 days.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Current Gauge dashboard, including enabled=false while the feature is opted out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GaugeDashboard" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/gauge/auth-sessions": { "post": { "summary": "Start assisted Gauge authentication", "description": "Starts a bounded provider-owned OAuth, device, or browser-assisted flow. Client and device credentials are never returned. GitHub device flow requires a registered OAuth client ID with device flow enabled.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GaugeAuthSessionCreate"}}}}, "responses": {"201": {"description": "Started authentication session.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GaugeAuthSession"}}}}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "409": {"description": "Gauge is disabled.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}}}}, "500": {"$ref": "#/components/responses/InternalError"}} } }, "/v1/gauge/auth-sessions/{id}": { "get": {"summary": "Poll a Gauge authentication session", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string", "maxLength": 160}}], "responses": {"200": {"description": "Current authentication progress.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GaugeAuthSession"}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "404": {"$ref": "#/components/responses/GaugeAuthSessionNotFound"}, "500": {"$ref": "#/components/responses/InternalError"}}}, "delete": {"summary": "Cancel a Gauge authentication session", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string", "maxLength": 160}}], "responses": {"200": {"description": "Cancelled authentication session.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GaugeAuthSession"}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "404": {"$ref": "#/components/responses/GaugeAuthSessionNotFound"}, "500": {"$ref": "#/components/responses/InternalError"}}} }, "/v1/gauge/readings": { "get": { "summary": "List cached Gauge readings", "description": "Returns the latest normalized, redacted reading for each matching account. Results are newest first and bounded to 200 records.", "parameters": [ {"name": "providerId", "in": "query", "schema": {"type": "string", "maxLength": 160}}, {"name": "accountId", "in": "query", "schema": {"type": "string", "maxLength": 160}}, {"name": "after", "in": "query", "schema": {"type": "string", "format": "date-time"}}, {"name": "before", "in": "query", "schema": {"type": "string", "format": "date-time"}}, {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50}}, {"name": "offset", "in": "query", "schema": {"type": "integer", "minimum": 0, "maximum": 1000000, "default": 0}} ], "responses": { "200": {"description": "A page of redacted Gauge readings.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GaugeReadingsResponse"}}}}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "500": {"$ref": "#/components/responses/InternalError"} } } }, "/v1/gauge/statuses": { "get": { "summary": "List Gauge provider and account statuses", "description": "Returns provider incidents/components separately from each account's local authentication and collection reachability.", "responses": { "200": {"description": "Provider and account status summaries.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GaugeStatusesResponse"}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "500": {"$ref": "#/components/responses/InternalError"} } } }, "/v1/gauge/recommendations": { "get": { "summary": "Get advisory Gauge recommendations", "description": "Returns a confidence-labelled Can I finish estimate plus better connected account candidates based only on cached redacted capacity, freshness, reachability, and provider status. Recommendations never switch accounts or routes automatically.", "parameters": [ {"name": "accountId", "in": "query", "schema": {"type": "string", "maxLength": 160}}, {"name": "model", "in": "query", "schema": {"type": "string", "maxLength": 320}}, {"name": "durationSeconds", "in": "query", "schema": {"type": "integer", "minimum": 300, "maximum": 604800, "default": 3600}} ], "responses": { "200": {"description": "Advisory recommendations and an optional work estimate.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GaugeRecommendationsResponse"}}}}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "409": {"description": "Gauge is disabled.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}}}}, "500": {"$ref": "#/components/responses/InternalError"} } } }, "/v1/gauge/capacity": { "get": { "summary": "Get the redacted Gauge capacity signal", "description": "Returns active-account capacity signals suitable for policy-controlled Smart Route decisions. When Gauge is disabled, enabled is false and data is empty.", "responses": { "200": {"description": "Gauge capacity signals.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GaugeCapacityResponse"}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "500": {"$ref": "#/components/responses/InternalError"} } } }, "/v1/gauge/diagnostics": { "get": { "summary": "Export redacted Gauge diagnostics", "description": "Returns bounded provider/account collection state with hashed local account references. It never returns credentials, credential references, identity labels, provider payloads, or private paths.", "responses": { "200": {"description": "Redacted Gauge diagnostics.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GaugeDiagnosticsResponse"}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "500": {"$ref": "#/components/responses/InternalError"} } } }, "/v1/gauge/activity": { "get": { "summary": "List detailed Gauge activity", "description": "Returns bounded, paginated activity from successful Gauge readings. Workspace labels are redacted before storage; prompts, responses, raw provider payloads, credentials, and absolute local paths are never returned. The default range is the trailing 30 days and one request may span at most 366 days. Time filters select buckets overlapping the half-open [after, before) interval; exact outer boundaries are excluded.", "parameters": [ {"name": "sourceId", "in": "query", "schema": {"type": "string", "maxLength": 160}}, {"name": "accountId", "in": "query", "schema": {"type": "string", "maxLength": 160}}, {"name": "providerId", "in": "query", "schema": {"type": "string", "maxLength": 160}}, {"name": "model", "in": "query", "schema": {"type": "string", "maxLength": 320}}, {"name": "project", "in": "query", "schema": {"type": "string", "maxLength": 320}}, {"name": "workspace", "in": "query", "schema": {"type": "string", "maxLength": 320}}, {"name": "source", "in": "query", "schema": {"type": "string", "maxLength": 160}}, {"name": "session", "in": "query", "schema": {"type": "string", "maxLength": 320}}, {"name": "after", "in": "query", "schema": {"type": "string", "format": "date-time"}}, {"name": "before", "in": "query", "schema": {"type": "string", "format": "date-time"}}, {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50}}, {"name": "offset", "in": "query", "schema": {"type": "integer", "minimum": 0, "maximum": 1000000, "default": 0}} ], "responses": { "200": { "description": "A page of redacted Gauge activity in newest-first order.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GaugeActivityResponse"}}} }, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "500": {"$ref": "#/components/responses/InternalError"} } } }, "/v1/gauge/budgets": { "get": { "summary": "List Gauge project budgets", "description": "Returns local project guardrails with provider-reported and estimated spend kept as separate fields. The selected basis alone determines counted spend.", "responses": { "200": {"description": "Gauge project budget statuses.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GaugeBudgetsResponse"}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "500": {"$ref": "#/components/responses/InternalError"} } }, "post": { "summary": "Create a Gauge project budget", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GaugeBudgetCreate"}}}}, "responses": { "201": {"description": "Created project budget status.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GaugeProjectBudgetStatus"}}}}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "500": {"$ref": "#/components/responses/InternalError"} } } }, "/v1/gauge/budgets/{id}": { "patch": { "summary": "Update a Gauge project budget", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string", "maxLength": 160}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GaugeBudgetUpdate"}}}}, "responses": { "200": {"description": "Updated project budget status.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GaugeProjectBudgetStatus"}}}}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "404": {"$ref": "#/components/responses/GaugeBudgetNotFound"}, "500": {"$ref": "#/components/responses/InternalError"} } }, "delete": { "summary": "Delete a Gauge project budget", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string", "maxLength": 160}}], "responses": { "200": {"description": "Deletion result.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GaugeBudgetDeleteResponse"}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "404": {"$ref": "#/components/responses/GaugeBudgetNotFound"}, "500": {"$ref": "#/components/responses/InternalError"} } } }, "/v1/gauge/alert-rules": { "get": { "summary": "List Gauge alert rules", "description": "Returns the local, opt-in alert rules in stable order. No rules exist until the user creates one.", "responses": { "200": {"description": "Gauge alert rules.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GaugeAlertRulesResponse"}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "500": {"$ref": "#/components/responses/InternalError"} } }, "post": { "summary": "Create a Gauge alert rule", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GaugeAlertRuleCreate"}}}}, "responses": { "201": {"description": "Created Gauge alert rule.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GaugeAlertRule"}}}}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "500": {"$ref": "#/components/responses/InternalError"} } } }, "/v1/gauge/alert-rules/{id}": { "patch": { "summary": "Update a Gauge alert rule", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string", "maxLength": 160}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GaugeAlertRuleUpdate"}}}}, "responses": { "200": {"description": "Updated Gauge alert rule.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GaugeAlertRule"}}}}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "404": {"$ref": "#/components/responses/GaugeAlertRuleNotFound"}, "500": {"$ref": "#/components/responses/InternalError"} } }, "delete": { "summary": "Delete a Gauge alert rule", "description": "Deletes the rule and only its Gauge-owned event history.", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string", "maxLength": 160}}], "responses": { "200": {"description": "Deletion result.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GaugeAlertDeleteResponse"}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "404": {"$ref": "#/components/responses/GaugeAlertRuleNotFound"}, "500": {"$ref": "#/components/responses/InternalError"} } } }, "/v1/gauge/alert-events": { "get": { "summary": "List Gauge alert events", "description": "Returns redacted, paginated alert history. The default range is 30 days and pending events are suitable for local notification delivery.", "parameters": [ {"name": "ruleId", "in": "query", "schema": {"type": "string", "maxLength": 160}}, {"name": "accountId", "in": "query", "schema": {"type": "string", "maxLength": 160}}, {"name": "providerId", "in": "query", "schema": {"type": "string", "maxLength": 160}}, {"name": "state", "in": "query", "schema": {"$ref": "#/components/schemas/GaugeAlertEventState"}}, {"name": "delivery", "in": "query", "schema": {"$ref": "#/components/schemas/GaugeAlertDeliveryState"}}, {"name": "after", "in": "query", "schema": {"type": "string", "format": "date-time"}}, {"name": "before", "in": "query", "schema": {"type": "string", "format": "date-time"}}, {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50}}, {"name": "offset", "in": "query", "schema": {"type": "integer", "minimum": 0, "maximum": 1000000, "default": 0}} ], "responses": { "200": {"description": "A page of Gauge alert events.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GaugeAlertEventsResponse"}}}}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "500": {"$ref": "#/components/responses/InternalError"} } } }, "/v1/gauge/alert-events/{id}": { "patch": { "summary": "Record local delivery of a Gauge alert event", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string", "maxLength": 160}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GaugeAlertDeliveryUpdate"}}}}, "responses": { "200": {"description": "Delivery state updated.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GaugeAlertDeliveryResponse"}}}}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "404": {"$ref": "#/components/responses/GaugeAlertEventNotFound"}, "500": {"$ref": "#/components/responses/InternalError"} } } }, "/v1/gauge/providers": { "get": { "summary": "List Gauge providers", "description": "Returns the complete Gauge provider catalog in stable order. Providers with no auth modes or capabilities are catalogued for parity tracking but are not yet connectable. The response contains no account or credential material.", "responses": { "200": { "description": "Gauge provider descriptors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GaugeProvidersResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/gauge/accounts": { "get": { "summary": "List Gauge accounts", "description": "Returns redacted connected-account summaries. The initial compatibility implementation projects configured Gauge sources as accounts; credential values and storage references are never returned.", "responses": { "200": { "description": "Redacted Gauge account summaries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GaugeAccountsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "summary": "Create a Gauge account", "description": "Creates one independently configured account for a provider/authentication adapter. Credentials are write-only and never echoed.", "requestBody": { "required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GaugeAccountCreate"}}} }, "responses": { "201": {"description": "Created redacted Gauge account.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GaugeAccountSummary"}}}}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "404": {"description": "The provider/authentication adapter is unavailable.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}}}}, "500": {"$ref": "#/components/responses/InternalError"} } } }, "/v1/gauge/accounts/{id}": { "patch": { "summary": "Update a Gauge account", "description": "Updates mutable account settings or replaces/clears its write-only credential.", "parameters": [{ "name": "id", "in": "path", "required": true, "description": "Stable local Gauge account ID.", "schema": {"type": "string"} }], "requestBody": { "required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GaugeAccountUpdate"}}} }, "responses": { "200": {"description": "Updated redacted Gauge account.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GaugeAccountSummary"}}}}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "404": {"description": "Gauge account not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}}}}, "500": {"$ref": "#/components/responses/InternalError"} } }, "delete": { "summary": "Delete a Gauge account", "description": "Deletes a user-created Gauge account, its Gauge-owned history, and its Gauge credential. Built-in compatibility sources must be disabled rather than deleted.", "parameters": [{ "name": "id", "in": "path", "required": true, "description": "Stable local Gauge account ID.", "schema": {"type": "string"} }], "responses": { "200": {"description": "Deletion result.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GaugeAccountDeleteResponse"}}}}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "404": {"description": "Gauge account not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}}}}, "500": {"$ref": "#/components/responses/InternalError"} } } }, "/v1/gauge/sources": { "get": { "summary": "List Gauge sources", "description": "Returns the available Gauge sources in stable display order. Each record reports only whether a credential is configured, never the credential value or its storage reference.", "responses": { "200": { "description": "Redacted Gauge source list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GaugeSourcesResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/gauge/sources/{id}": { "put": { "summary": "Configure a Gauge source", "description": "Enables or disables one Gauge source, stores or clears its reporting credential, and updates allow-listed non-secret source configuration. Credentials are write-only and are represented in the response only by credentialConfigured.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Stable Gauge source ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GaugeSourceUpdate" } } } }, "responses": { "200": { "description": "Updated redacted Gauge source.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GaugeSourceSummary" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "The Gauge source ID is unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/gauge/refresh": { "post": { "summary": "Refresh Gauge sources", "description": "Refreshes the requested Gauge sources, or every enabled source when sourceIds is omitted. Provider checks run concurrently with bounded concurrency and timeouts. A source-level collection failure is returned as a redacted outcome so the last successful snapshot remains available.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GaugeRefreshRequest" } } } }, "responses": { "200": { "description": "Redacted refresh outcomes in requested source order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GaugeRefreshResponse" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "At least one requested Gauge source ID is unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Gauge is disabled, a requested source is disabled, or a refresh is already running.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/gauge/history": { "delete": { "summary": "Delete Gauge history", "description": "Deletes compact Gauge chart history for one source or for all sources. Current readings, source setup, and stored reporting credentials are unchanged.", "parameters": [ { "name": "sourceId", "in": "query", "description": "Optional stable source ID. Omit to delete all Gauge history.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Number of deleted snapshots.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GaugeDeleteHistoryResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "The requested Gauge source ID is unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/capabilities": { "get": { "summary": "Get client capabilities", "description": "Returns the token-protected discovery document for API-first clients. The response contains stable endpoint family IDs, route names, provider kinds, global action identifiers, per-provider-kind action support, registry sources, shared scopes, preset-scope compatibility data, and feature surfaces. It intentionally uses IDs rather than display labels and omits provider records, provider credentials, credential references, local paths, runtime roots, and generated artifact paths.", "responses": { "200": { "description": "Stable client discovery document for this Nexus build.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Capabilities" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/hardware/telemetry": { "get": { "summary": "Get hardware telemetry", "description": "Returns token-protected, public-safe host and accelerator telemetry for local model-fit decisions. The response may include OS, architecture, logical CPU count, total and available system memory, GPU names, GPU vendor/backend, memory kind, reported or estimated GPU memory, and confidence labels. It intentionally omits serial numbers, UUIDs, PCI addresses, local filesystem paths, runtime roots, credentials, provider records, and local Nexus token values.", "responses": { "200": { "description": "Hardware telemetry for the running Nexus Runtime host.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HardwareTelemetry" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/hardware/refresh": { "post": { "summary": "Refresh hardware telemetry", "description": "Reprobes the local host and returns the same public-safe hardware telemetry contract as GET /v1/hardware/telemetry. This action does not install drivers or run a system package manager.", "responses": { "200": { "description": "Fresh hardware telemetry for the running Nexus Runtime host.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HardwareTelemetry" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/audit-events": { "get": { "summary": "List audit events", "description": "Returns append-only audit events newest-first. Query filters are validated before storage access. Response metadata is allow-listed and never exposes provider credentials, local Nexus token values, raw request bodies, local filesystem paths, generated artifact paths, or arbitrary stored metadata.", "parameters": [ { "name": "action", "in": "query", "schema": { "$ref": "#/components/schemas/AuditAction" } }, { "name": "resourceType", "in": "query", "schema": { "$ref": "#/components/schemas/AuditResourceType" } }, { "name": "resourceId", "in": "query", "schema": { "type": "string" } }, { "name": "actorType", "in": "query", "schema": { "$ref": "#/components/schemas/AuditActorType" } }, { "name": "actorId", "in": "query", "schema": { "type": "string" } }, { "name": "requestId", "in": "query", "schema": { "type": "string" } }, { "name": "createdAfter", "in": "query", "description": "Inclusive RFC3339 lower bound.", "schema": { "type": "string", "format": "date-time" } }, { "name": "createdBefore", "in": "query", "description": "Inclusive RFC3339 upper bound.", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ], "responses": { "200": { "description": "Filtered audit event list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditEventList" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/usage/summary": { "get": { "summary": "Get usage summary", "description": "Returns total requests, failed requests, token counters, and tool-call counts for the filtered local-day range. Usage metrics are aggregate local counters derived from provider-reported usage; they never include prompt text, response text, tool arguments, headers, or credentials, and raw per-request rows are not exposed.", "parameters": [ { "name": "from", "in": "query", "description": "Inclusive first local day (YYYY-MM-DD). Defaults to 364 days before the effective to date.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "description": "Inclusive last local day (YYYY-MM-DD). Defaults to the current local day.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "providerId", "in": "query", "description": "Restrict aggregation to one provider.", "schema": { "type": "string" } }, { "name": "modelId", "in": "query", "description": "Restrict aggregation to one resolved catalog model ID.", "schema": { "type": "string" } }, { "name": "tokenId", "in": "query", "description": "Restrict aggregation to requests authenticated by one local Nexus token.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get usage summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageSummary" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/usage/daily": { "get": { "summary": "List daily usage", "description": "Returns sparse ascending per-day usage buckets for heatmap rendering. Days without traffic are omitted; clients zero-fill. Usage metrics are aggregate local counters derived from provider-reported usage; they never include prompt text, response text, tool arguments, headers, or credentials, and raw per-request rows are not exposed.", "parameters": [ { "name": "from", "in": "query", "description": "Inclusive first local day (YYYY-MM-DD). Defaults to 364 days before the effective to date.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "description": "Inclusive last local day (YYYY-MM-DD). Defaults to the current local day.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "providerId", "in": "query", "description": "Restrict aggregation to one provider.", "schema": { "type": "string" } }, { "name": "modelId", "in": "query", "description": "Restrict aggregation to one resolved catalog model ID.", "schema": { "type": "string" } }, { "name": "tokenId", "in": "query", "description": "Restrict aggregation to requests authenticated by one local Nexus token.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List daily usage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageDailyList" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/usage/breakdown": { "get": { "summary": "Get usage breakdown", "description": "Returns usage grouped by provider, model, provider and model, or local token, ranked by total tokens. Usage metrics are aggregate local counters derived from provider-reported usage; they never include prompt text, response text, tool arguments, headers, or credentials, and raw per-request rows are not exposed.", "parameters": [ { "name": "from", "in": "query", "description": "Inclusive first local day (YYYY-MM-DD). Defaults to 364 days before the effective to date.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "description": "Inclusive last local day (YYYY-MM-DD). Defaults to the current local day.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "providerId", "in": "query", "description": "Restrict aggregation to one provider.", "schema": { "type": "string" } }, { "name": "modelId", "in": "query", "description": "Restrict aggregation to one resolved catalog model ID.", "schema": { "type": "string" } }, { "name": "tokenId", "in": "query", "description": "Restrict aggregation to requests authenticated by one local Nexus token.", "schema": { "type": "string" } }, { "name": "groupBy", "in": "query", "description": "Breakdown dimension.", "schema": { "$ref": "#/components/schemas/UsageGroupBy" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } } ], "responses": { "200": { "description": "Get usage breakdown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBreakdownList" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/usage/tools": { "get": { "summary": "List top tools", "description": "Returns tool names ranked by recorded call count. Only tool names and counts are stored; arguments and results are never recorded. Usage metrics are aggregate local counters derived from provider-reported usage; they never include prompt text, response text, tool arguments, headers, or credentials, and raw per-request rows are not exposed.", "parameters": [ { "name": "from", "in": "query", "description": "Inclusive first local day (YYYY-MM-DD). Defaults to 364 days before the effective to date.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "description": "Inclusive last local day (YYYY-MM-DD). Defaults to the current local day.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "providerId", "in": "query", "description": "Restrict aggregation to one provider.", "schema": { "type": "string" } }, { "name": "modelId", "in": "query", "description": "Restrict aggregation to one resolved catalog model ID.", "schema": { "type": "string" } }, { "name": "tokenId", "in": "query", "description": "Restrict aggregation to requests authenticated by one local Nexus token.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 20 } } ], "responses": { "200": { "description": "List top tools.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageToolList" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/usage/routes": { "get": { "summary": "List Smart Route usage", "description": "Returns Smart Route rows ranked by request count. Rows expose stable route pack slugs, selected route IDs, resolved target model IDs, provider IDs, fallback status, fallback reason codes, and aggregate counters only. Prompt text, classifier output, route descriptions, headers, and credentials are never stored or returned.", "parameters": [ { "name": "from", "in": "query", "description": "Inclusive first local day (YYYY-MM-DD). Defaults to 364 days before the effective to date.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "description": "Inclusive last local day (YYYY-MM-DD). Defaults to the current local day.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "providerId", "in": "query", "description": "Restrict aggregation to one provider.", "schema": { "type": "string" } }, { "name": "modelId", "in": "query", "description": "Restrict aggregation to one resolved catalog model ID.", "schema": { "type": "string" } }, { "name": "tokenId", "in": "query", "description": "Restrict aggregation to requests authenticated by one local Nexus token.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } } ], "responses": { "200": { "description": "List Smart Route usage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageRouteList" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/usage/acceleration": { "get": { "summary": "List acceleration usage", "description": "Returns speculative decoding and local acceleration aggregates with accelerated rows first, then ranked by output token volume. Rows expose stable provider IDs, model IDs, acceleration modes, draft model IDs, and counters only. Speedup and estimated time saved are populated only when non-accelerated same-model baseline traffic exists in the selected range. Draft acceptance is populated only when the runtime reports draft counters. Prompt text, response text, runtime flags, local paths, headers, and credentials are never stored or returned.", "parameters": [ { "name": "from", "in": "query", "description": "Inclusive first local day (YYYY-MM-DD). Defaults to 364 days before the effective to date.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "description": "Inclusive last local day (YYYY-MM-DD). Defaults to the current local day.", "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "providerId", "in": "query", "description": "Restrict aggregation to one provider.", "schema": { "type": "string" } }, { "name": "modelId", "in": "query", "description": "Restrict aggregation to one resolved catalog model ID.", "schema": { "type": "string" } }, { "name": "tokenId", "in": "query", "description": "Restrict aggregation to requests authenticated by one local Nexus token.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } } ], "responses": { "200": { "description": "List acceleration usage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageAccelerationList" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/models": { "get": { "summary": "List models", "description": "Returns an OpenAI-compatible model list by default. When the request includes anthropic-version, Nexus returns Anthropic's paginated model list shape. In both modes the caller authenticates with a local Nexus token, never an upstream provider key. Enabled providers with autoProxyModels enabled contribute provider-returned models automatically using / IDs; explicit catalog model records with the same ID take precedence. Presets are exposed as synthetic models with @preset/{slug} IDs, the preset display name, and the target model's endpoint families. Smart Route packs are exposed as synthetic models with @route/{slug} IDs, the route-pack display name, safe route metadata, and generation endpoint families guaranteed by their fallback model. OpenAI-compatible and Anthropic-compatible clients can discover both like normal gateway models. Hidden models, models attached to disabled providers or internal provider kinds, and presets or route packs targeting those models are omitted from public model discovery.", "parameters": [ { "name": "anthropic-version", "in": "header", "required": false, "description": "When present, selects the Anthropic-compatible response shape for Anthropic SDKs.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Anthropic-compatible page size. Valid only for Anthropic-shaped responses.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 20 } }, { "name": "after_id", "in": "query", "required": false, "description": "Anthropic-compatible cursor after which to return models.", "schema": { "type": "string" } }, { "name": "before_id", "in": "query", "required": false, "description": "Anthropic-compatible cursor before which to return models.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Models available to the local Nexus gateway.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ModelList" }, { "$ref": "#/components/schemas/AnthropicModelList" } ] } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/loaded-models": { "get": { "summary": "List models loaded in runtime memory", "description": "Reports which local models are resident in runtime memory right now, with size, VRAM use, and keep-alive expiry where the runtime provides them, plus a per-service probe outcome so clients can distinguish an empty result from an unreachable runtime. Occupancy comes from runtime-native APIs (Ollama /api/ps and llama.cpp /models); runtimes without an occupancy API are omitted. Responses never expose local paths or provider credentials.", "responses": { "200": { "description": "Loaded model report.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoadedModelsReport" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/model-library/health": { "get": { "summary": "Scan model library health", "description": "Runs a read-only reconciliation of catalog records against Nexus-managed storage and runtime-reported models, including Ollama manifest and blob integrity plus llama.cpp runtime availability. The report lists concrete drifts (missing files, interrupted or externally modified downloads detected by size mismatch, orphan files, stale or uncataloged runtime models) with a suggested repair that maps onto existing model actions (sync, pull, delete, or none). This route never mutates library state, and unreachable runtimes are reported as unverifiable rather than unhealthy. Paths in issues are relative to managed storage; absolute local paths are never returned.", "responses": { "200": { "description": "Library health report.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibraryHealthReport" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/control/models": { "get": { "summary": "List catalog models", "description": "Returns catalog model records for trusted Nexus control surfaces. Hidden models are included so local management clients can show, edit, hide, or unhide them. Models attached to internal provider kinds are omitted.", "responses": { "200": { "description": "Catalog model records visible to trusted control surfaces.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } } }, "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/model-registry/search": { "get": { "summary": "Search external model registries", "description": "Searches supported external model registries. The initial sources are Hugging Face Hub and Ollama's public model search. Multi-source searches return successful source results with stable warnings for unavailable sources; if every requested source fails, Nexus returns MODEL_REGISTRY_REQUEST_FAILED.", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search query. Hugging Face model URLs are accepted and searched as their owner/repo repository ID.", "schema": { "type": "string", "minLength": 1 } }, { "name": "source", "in": "query", "required": false, "description": "Optional source filter. Repeat the parameter or pass comma-separated values. When omitted or set to all, every supported source is searched.", "schema": { "oneOf": [ { "$ref": "#/components/schemas/ModelRegistrySource" }, { "type": "string", "const": "all" } ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum results per source.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "responses": { "200": { "description": "Model search results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelSearchList" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/ModelRegistryRequestFailed" } } } }, "/v1/model-install-candidates/search": { "get": { "summary": "Search installable model candidates", "description": "Searches only the registry sources needed by Nexus-installed local runtimes and returns model-action payloads clients can use to install compatible models. Ollama services produce Ollama pull candidates; MLX services produce Hugging Face snapshot pull candidates; llama.cpp services produce Hugging Face GGUF candidates and mark results that still need a GGUF file selection.", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search query. Hugging Face model URLs are accepted and searched as their owner/repo repository ID.", "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum install candidates returned in this page.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of previously loaded install candidates to skip.", "schema": { "type": "integer", "minimum": 0, "maximum": 450, "default": 0 } } ], "responses": { "200": { "description": "Installable model candidates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelInstallCandidateList" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/ModelRegistryRequestFailed" } } } }, "/v1/model-actions": { "post": { "summary": "Request a model action", "description": "Queues a model action. Runtime-backed actions can pull, delete, load, unload, or sync Ollama models; pull GGUF files from Hugging Face, import local GGUF files, sync the configured Nexus llama.cpp models subdirectory, safely delete only Nexus-managed relative GGUF records, and ask the installed, reachable native llama.cpp router to load or unload a model through POST /models/load and POST /models/unload without exposing absolute local paths in job metadata; pull Hugging Face snapshots into the Nexus-owned MLX model cache, delete only Nexus-managed MLX cache records, and sync MLX models from the runtime's OpenAI-compatible /v1/models list on macOS without credentials while skipping absolute or path-shaped model IDs; and sync the distributed cluster's private rank-0 /v1/models list as cluster/ records with startup retry. A successful llama.cpp load/unload job means the router accepted the request; clients observe loading and loaded occupancy through the loaded-model snapshot backed by GET /models. MLX pull can run before the MLX runtime is installed; MLX sync and delete require a recorded Nexus-managed runtime install. Provider-backed sync can import available OpenAI, Anthropic, and OpenRouter models through the stored provider credential without exposing that credential to clients. If another queued or running runtime/model/provider-model job already targets the same service or provider, Nexus returns RESOURCE_IN_USE with only the conflicting job ID, kind, state, and target ID.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelActionRequest" } } } }, "responses": { "202": { "description": "Model action job queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "The requested runtime service or provider could not be resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "$ref": "#/components/responses/ResourceInUse" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/models/fit": { "post": { "summary": "Estimate memory fit from architecture dims", "description": "Computes an itemised memory-fit estimate (weights, KV cache, overhead) for a model whose architecture dimensions are supplied by the caller, against the host's current memory ceiling. The math is architecture-aware (MHA, GQA, MLA, MoE, quantized KV) and source-grounded in llama.cpp and mlx-lm.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FitRequest" } } } }, "responses": { "200": { "description": "Fit estimate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FitResult" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/models/fit-candidate": { "post": { "summary": "Estimate memory fit for a remote model", "description": "Lazily extracts a remote model's architecture dimensions (Hugging Face GGUF header or MLX config.json, cached per revision) and returns a memory-fit estimate. Designed for on-demand probing of individual model cards so search latency is unaffected; each unique model is probed at most once. Extraction failures degrade to an 'unknown' verdict with a lower-bound estimate rather than an error.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FitCandidateRequest" } } } }, "responses": { "200": { "description": "Fit estimate (or 'unknown' verdict when extraction failed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FitCandidateResult" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/model-placement-profiles/{id}": { "get": { "summary": "Get a model placement profile", "description": "Returns the saved runtime-neutral GPU policy for a local model, or a revision-1 balanced default when no profile has been saved. Native GPU UUIDs, runtime flags, and local paths are never returned.", "parameters": [{ "$ref": "#/components/parameters/ModelID" }], "responses": { "200": { "description": "Saved or default placement profile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelPlacementProfile" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ModelNotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "summary": "Replace a model placement profile", "description": "Replaces the client-writable profile fields using optimistic revision control. The server owns modelId, object, revision advancement, and updatedAt. Unknown fields, raw runtime flags, filesystem paths, and native device selectors are rejected.", "parameters": [{ "$ref": "#/components/parameters/ModelID" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelPlacementProfileInput" } } } }, "responses": { "200": { "description": "Updated placement profile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelPlacementProfile" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ModelNotFound" }, "409": { "description": "The expected revision is stale.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/model-placement-plans/{id}": { "post": { "summary": "Preview model placement", "description": "Builds a dry-run plan from the saved profile or an optional unsaved profile preview. Model metadata, current memory, runtime backend, and opaque GPU inventory are resolved by Nexus; clients cannot supply memory figures or native selectors.", "parameters": [{ "$ref": "#/components/parameters/ModelID" }], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelPlacementPlanInput" } } } }, "responses": { "200": { "description": "Current dry-run placement plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelPlacementPlan" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ModelNotFound" }, "409": { "description": "The preview revision is stale or the runtime is unsupported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Current model, runtime, or hardware metadata is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/model-placement-applications/{id}": { "post": { "summary": "Apply and verify model placement", "description": "Queues a tracked apply job for one saved profile revision. The worker reloads the saved profile and rebuilds the plan from current hardware immediately before runtime mutation, then loads the model, verifies effective placement, and restores the last working placement when a later step fails.", "parameters": [{ "$ref": "#/components/parameters/ModelID" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelPlacementApplyInput" } } } }, "responses": { "202": { "description": "Placement apply job queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ModelNotFound" }, "409": { "description": "The revision is stale, the current plan needs approval, or another model operation is active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Placement is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/model-placement-rollbacks/{id}": { "post": { "summary": "Restore the previous verified placement", "parameters": [{ "$ref": "#/components/parameters/ModelID" }], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelPlacementRollbackInput" } } } }, "responses": { "202": { "description": "Placement rollback job queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ModelNotFound" }, "409": { "description": "No earlier verified placement exists or another model operation is active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Placement is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/model-placement-states/{id}": { "get": { "summary": "Get requested, active, and last-working placement state", "parameters": [{ "$ref": "#/components/parameters/ModelID" }], "responses": { "200": { "description": "Placement lifecycle state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelPlacementState" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ModelNotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/model-effective-placements/{id}": { "get": { "summary": "Get verified effective placement", "description": "Returns what the runtime proved is active, which can differ from the requested profile. A model without verified evidence returns MODEL_PLACEMENT_UNAVAILABLE.", "parameters": [{ "$ref": "#/components/parameters/ModelID" }], "responses": { "200": { "description": "Verified or partially verified effective placement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelEffectivePlacement" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Model or effective placement was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/model-benchmarks/{id}": { "get": { "summary": "List model benchmark history", "parameters": [ { "$ref": "#/components/parameters/ModelID" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "before", "in": "query", "description": "Continue after this benchmark ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Newest-first benchmark history.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelBenchmarkList" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ModelNotFound" }, "503": { "description": "Benchmarks are unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "summary": "Run a controlled model benchmark", "description": "Queues a bounded campaign using one fixed local workload. Quick compares the current, automatic, and maximum-GPU placements when distinct and applicable. Expert also tries bounded per-device and multi-GPU placements. Quality-affecting settings remain unchanged, the original placement and load state are restored, and prompts and generated text are never stored.", "parameters": [{ "$ref": "#/components/parameters/ModelID" }], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelBenchmarkInput" } } } }, "responses": { "202": { "description": "Benchmark job queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ModelNotFound" }, "409": { "description": "Another operation is active for this model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Benchmarks are unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/model-benchmark-results/{id}": { "get": { "summary": "Get one benchmark result", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^bench-[A-Za-z0-9_-]+$" } }], "responses": { "200": { "description": "Benchmark result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelBenchmark" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Benchmark result not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Benchmarks are unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/model-benchmark-recommendations/{id}": { "get": { "summary": "Get the best comparable benchmark recommendation", "description": "Returns only quality-equivalent recommendations. stale and staleReasonCodes explain when the model, hardware, runtime, or benchmark protocol changed.", "parameters": [{ "$ref": "#/components/parameters/ModelID" }], "responses": { "200": { "description": "Best comparable recommendation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelBenchmarkRecommendation" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No comparable recommendation exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "The model has no active verified placement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Benchmarks are unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/models/{id}": { "get": { "summary": "Get model", "description": "Returns one model by ID, alias, auto-proxied / ID, @preset/{slug} synthetic preset model ID, or @route/{slug} synthetic Smart Route model ID. By default, Nexus returns an OpenAI-compatible model object with additive Nexus catalog fields. Hidden models, models owned by disabled providers or internal provider kinds, and presets or route packs targeting those models return MODEL_NOT_FOUND. When the request includes anthropic-version, Nexus returns an Anthropic-compatible model object for SDK model retrieval.", "parameters": [ { "$ref": "#/components/parameters/ModelID" }, { "name": "anthropic-version", "in": "header", "required": false, "description": "When present, selects the Anthropic-compatible model response shape.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Configured model.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/OpenAIModelInfo" }, { "$ref": "#/components/schemas/AnthropicModelInfo" } ] } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ModelNotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "summary": "Create or replace model", "description": "Stores model catalog metadata in SQLite. The providerId must reference an existing public provider, endpointFamilies must be supported by that provider's kind, and scope defaults to local when omitted. Set hidden to true to omit the model from /v1/models and reject direct model or alias routing for clients. Internal provider kinds are rejected as if the provider does not exist. API-visible metadata rejects credential-shaped keys such as apiKey, authorization, token, and secret.", "parameters": [ { "$ref": "#/components/parameters/ModelID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelInput" } } } }, "responses": { "200": { "description": "Model updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" } } } }, "201": { "description": "Model created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "summary": "Delete model", "description": "Deletes a model catalog record. If any preset references the model, Nexus returns RESOURCE_IN_USE and leaves both the model and preset intact.", "parameters": [ { "$ref": "#/components/parameters/ModelID" } ], "responses": { "204": { "description": "Model deleted." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ModelNotFound" }, "409": { "$ref": "#/components/responses/ResourceInUse" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/chat/completions": { "post": { "summary": "OpenAI-style chat completions gateway", "description": "Accepts an OpenAI-style chat completions body with model and messages, resolves direct model IDs, model aliases, @preset slugs, and @route slugs, and invokes a configured OpenAI-compatible adapter. Nexus forwards only allow-listed non-secret provider request headers, including OpenAI-Organization, OpenAI-Project, OpenAI-Beta, and X-Client-Request-Id for OpenAI providers and HTTP-Referer, X-OpenRouter-Title, X-Title, X-OpenRouter-Categories, and X-OpenRouter-Experimental-Metadata for OpenRouter providers. Nexus validates caller-supplied X-Client-Request-Id values as ASCII and at most 512 bytes before credential lookup, validates X-OpenRouter-Experimental-Metadata values as enabled or disabled before credential lookup, fills X-Client-Request-Id with the generated Nexus request ID when the caller omits it, resolves upstream credentials from the local vault, forwards provider X-Request-Id/request-id response aliases when present, and strips hop-by-hop, credential-bearing, or provider CORS response headers.", "requestBody": { "$ref": "#/components/requestBodies/OpenAIChatCompletionsRequest" }, "responses": { "200": { "$ref": "#/components/responses/ProxiedProviderResponse" }, "400": { "$ref": "#/components/responses/InvalidGatewayRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ModelNotFound" }, "500": { "$ref": "#/components/responses/InternalError" }, "501": { "$ref": "#/components/responses/ProviderNotConfigured" }, "502": { "$ref": "#/components/responses/ProviderRequestFailed" } } } }, "/v1/embeddings": { "post": { "summary": "OpenAI-style embeddings gateway", "description": "Accepts an OpenAI-style embeddings body with model and input, resolves direct model IDs, model aliases, and @preset slugs, and invokes a configured OpenAI-compatible adapter. Smart Route @route slugs are intentionally unsupported for embeddings in the first milestone. Nexus forwards only allow-listed non-secret provider request headers, including OpenAI-Organization, OpenAI-Project, OpenAI-Beta, and X-Client-Request-Id for OpenAI providers and HTTP-Referer, X-OpenRouter-Title, X-Title, X-OpenRouter-Categories, and X-OpenRouter-Experimental-Metadata for OpenRouter providers. Nexus validates caller-supplied X-Client-Request-Id values as ASCII and at most 512 bytes before credential lookup, validates X-OpenRouter-Experimental-Metadata values as enabled or disabled before credential lookup, fills X-Client-Request-Id with the generated Nexus request ID when the caller omits it, resolves upstream credentials from the local vault, forwards provider X-Request-Id/request-id response aliases when present, and strips hop-by-hop, credential-bearing, or provider CORS response headers.", "requestBody": { "$ref": "#/components/requestBodies/OpenAIEmbeddingsRequest" }, "responses": { "200": { "$ref": "#/components/responses/ProxiedProviderResponse" }, "400": { "$ref": "#/components/responses/InvalidGatewayRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ModelNotFound" }, "500": { "$ref": "#/components/responses/InternalError" }, "501": { "$ref": "#/components/responses/ProviderNotConfigured" }, "502": { "$ref": "#/components/responses/ProviderRequestFailed" } } } }, "/v1/images/generations": { "post": { "summary": "Generate images through the gateway", "description": "OpenAI-shaped image generation routed by local Nexus model or preset. The request body passes through to the selected provider after shallow validation (prompt is required); provider-specific fields such as size, quality, and output format flow through untouched. Providers that stream partial images over SSE are relayed transparently. Supported by OpenAI, OpenRouter, Ollama (upstream-experimental), and generic OpenAI-compatible local servers. Requests are not token-metered.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageGenerationRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/ProxiedProviderResponse" }, "400": { "$ref": "#/components/responses/InvalidGatewayRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ModelNotFound" }, "500": { "$ref": "#/components/responses/InternalError" }, "501": { "$ref": "#/components/responses/ProviderNotConfigured" }, "502": { "$ref": "#/components/responses/ProviderRequestFailed" } } } }, "/v1/images/edits": { "post": { "summary": "Edit images through the gateway", "description": "OpenAI-shaped image edit routed by local Nexus model ID or alias. The request must be multipart/form-data with exactly one model field plus prompt and image or image[] file parts. Query, repeated, array-shaped, or file-valued model selectors are rejected. Other provider fields such as mask, size, quality, and output format flow through untouched. Multipart routes do not accept preset or route-pack references and are limited to 268435456 bytes per request. Requests are not token-metered.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ImageEditMultipartRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/ProxiedProviderResponse" }, "400": { "$ref": "#/components/responses/InvalidGatewayRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ModelNotFound" }, "413": { "$ref": "#/components/responses/MultipartRequestTooLarge" }, "500": { "$ref": "#/components/responses/InternalError" }, "501": { "$ref": "#/components/responses/ProviderNotConfigured" }, "502": { "$ref": "#/components/responses/ProviderRequestFailed" } } } }, "/v1/audio/speech": { "post": { "summary": "Synthesize speech through the gateway", "description": "OpenAI-shaped text-to-speech routed by local Nexus model or preset. The request body passes through after shallow validation (input is required); voice and format fields flow through untouched. The upstream response body is binary audio and is relayed byte-for-byte with its content type. Supported by OpenAI, OpenRouter, and generic OpenAI-compatible local servers. Requests are not token-metered.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudioSpeechRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/ProxiedProviderResponse" }, "400": { "$ref": "#/components/responses/InvalidGatewayRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ModelNotFound" }, "500": { "$ref": "#/components/responses/InternalError" }, "501": { "$ref": "#/components/responses/ProviderNotConfigured" }, "502": { "$ref": "#/components/responses/ProviderRequestFailed" } } } }, "/v1/audio/transcriptions": { "post": { "summary": "Transcribe audio through the gateway", "description": "OpenAI-shaped speech-to-text routed by local Nexus model ID or alias. Multipart requests must include exactly one model form field plus a file part; query, repeated, array-shaped, or file-valued model selectors are rejected. The JSON variant requires input_audio for providers that support base64 audio input. Additional transcription fields such as language, prompt, temperature, response_format, and stream flow through untouched. Multipart routes do not accept preset or route-pack references and are limited to 268435456 bytes per request. Requests are not token-metered.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/AudioTranscriptionMultipartRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/AudioTranscriptionJSONRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/ProxiedProviderResponse" }, "400": { "$ref": "#/components/responses/InvalidGatewayRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ModelNotFound" }, "413": { "$ref": "#/components/responses/MultipartRequestTooLarge" }, "500": { "$ref": "#/components/responses/InternalError" }, "501": { "$ref": "#/components/responses/ProviderNotConfigured" }, "502": { "$ref": "#/components/responses/ProviderRequestFailed" } } } }, "/v1/rerank": { "post": { "summary": "Rerank documents through the gateway", "description": "Vendor-neutral rerank contract (Jina/Cohere shape) routed by local Nexus model or preset: query plus documents in, indexed relevance scores out. Served locally by llama.cpp (reranker models) and vLLM at the same path, so responses relay verbatim. Requests are not token-metered.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RerankRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/ProxiedProviderResponse" }, "400": { "$ref": "#/components/responses/InvalidGatewayRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ModelNotFound" }, "500": { "$ref": "#/components/responses/InternalError" }, "501": { "$ref": "#/components/responses/ProviderNotConfigured" }, "502": { "$ref": "#/components/responses/ProviderRequestFailed" } } } }, "/v1/responses": { "post": { "summary": "OpenAI Responses-style gateway", "description": "Accepts an OpenAI Responses-style body with model, resolves direct model IDs, model aliases, @preset slugs, and @route slugs, and invokes a configured OpenAI-compatible adapter. Nexus forwards only allow-listed non-secret provider request headers, including OpenAI-Organization, OpenAI-Project, OpenAI-Beta, and X-Client-Request-Id for OpenAI providers and HTTP-Referer, X-OpenRouter-Title, X-Title, X-OpenRouter-Categories, and X-OpenRouter-Experimental-Metadata for OpenRouter providers. Nexus validates caller-supplied X-Client-Request-Id values as ASCII and at most 512 bytes before credential lookup, validates X-OpenRouter-Experimental-Metadata values as enabled or disabled before credential lookup, fills X-Client-Request-Id with the generated Nexus request ID when the caller omits it, resolves upstream credentials from the local vault, forwards provider X-Request-Id/request-id response aliases when present, and strips hop-by-hop, credential-bearing, or provider CORS response headers.", "requestBody": { "$ref": "#/components/requestBodies/OpenAIResponsesRequest" }, "responses": { "200": { "$ref": "#/components/responses/ProxiedProviderResponse" }, "400": { "$ref": "#/components/responses/InvalidGatewayRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ModelNotFound" }, "500": { "$ref": "#/components/responses/InternalError" }, "501": { "$ref": "#/components/responses/ProviderNotConfigured" }, "502": { "$ref": "#/components/responses/ProviderRequestFailed" } } } }, "/v1/responses/input_tokens": { "post": { "summary": "OpenAI Responses input-token gateway", "description": "Accepts an OpenAI Responses input-token body with model, resolves direct model IDs, model aliases, and @preset slugs, and invokes the provider-native Responses input-token route through a configured OpenAI-compatible adapter. Smart Route @route slugs are intentionally unsupported for token counting in the first milestone. Nexus owns the upstream sibling path after model/provider routing, forwards only allow-listed non-secret provider request headers, resolves upstream credentials from the local vault, forwards provider X-Request-Id/request-id response aliases when present, and strips hop-by-hop, credential-bearing, or provider CORS response headers.", "requestBody": { "$ref": "#/components/requestBodies/OpenAIResponsesInputTokensRequest" }, "responses": { "200": { "$ref": "#/components/responses/ProxiedProviderResponse" }, "400": { "$ref": "#/components/responses/InvalidGatewayRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ModelNotFound" }, "500": { "$ref": "#/components/responses/InternalError" }, "501": { "$ref": "#/components/responses/ProviderNotConfigured" }, "502": { "$ref": "#/components/responses/ProviderRequestFailed" } } } }, "/v1/responses/compact": { "post": { "summary": "OpenAI Responses compact gateway", "description": "Accepts an OpenAI Responses compact body with model, resolves direct model IDs, model aliases, and @preset slugs, and invokes the provider-native Responses compact route through a configured OpenAI-compatible adapter. Smart Route @route slugs are intentionally unsupported for compact sibling routes in the first milestone. Nexus owns the upstream sibling path after model/provider routing, forwards only allow-listed non-secret provider request headers, resolves upstream credentials from the local vault, forwards provider X-Request-Id/request-id response aliases when present, and strips hop-by-hop, credential-bearing, or provider CORS response headers.", "requestBody": { "$ref": "#/components/requestBodies/OpenAIResponsesCompactRequest" }, "responses": { "200": { "$ref": "#/components/responses/ProxiedProviderResponse" }, "400": { "$ref": "#/components/responses/InvalidGatewayRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ModelNotFound" }, "500": { "$ref": "#/components/responses/InternalError" }, "501": { "$ref": "#/components/responses/ProviderNotConfigured" }, "502": { "$ref": "#/components/responses/ProviderRequestFailed" } } } }, "/v1/responses/{id}": { "get": { "summary": "Retrieve OpenAI Responses record", "description": "Retrieves an OpenAI Responses record by routing through the original provider/model pair recorded from a previous successful non-streaming Responses create call. Provider-supported query parameters, including stream=true, are forwarded after Nexus resolves the stored route. Nexus stores only the response ID, provider ID, model ID, creation time, and local routing metadata; request bodies, generated output, and provider credentials are not stored in the route index.", "parameters": [ { "$ref": "#/components/parameters/ResponseID" } ], "responses": { "200": { "$ref": "#/components/responses/ProxiedProviderResponse" }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ResponseNotFound" }, "500": { "$ref": "#/components/responses/InternalError" }, "501": { "$ref": "#/components/responses/ProviderNotConfigured" }, "502": { "$ref": "#/components/responses/ProviderRequestFailed" } } }, "delete": { "summary": "Delete OpenAI Responses record", "description": "Deletes an OpenAI Responses record through the original provider/model route. When the provider returns a successful response, Nexus removes only its local response-route index for that ID.", "parameters": [ { "$ref": "#/components/parameters/ResponseID" } ], "responses": { "200": { "$ref": "#/components/responses/ProxiedProviderResponse" }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ResponseNotFound" }, "500": { "$ref": "#/components/responses/InternalError" }, "501": { "$ref": "#/components/responses/ProviderNotConfigured" }, "502": { "$ref": "#/components/responses/ProviderRequestFailed" } } } }, "/v1/responses/{id}/input_items": { "get": { "summary": "List OpenAI Responses input items", "description": "Lists input items for an OpenAI Responses record by routing through the original provider/model pair. Nexus forwards the caller query string after resolving the locally indexed response route and server-side provider credential.", "parameters": [ { "$ref": "#/components/parameters/ResponseID" } ], "responses": { "200": { "$ref": "#/components/responses/ProxiedProviderResponse" }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ResponseNotFound" }, "500": { "$ref": "#/components/responses/InternalError" }, "501": { "$ref": "#/components/responses/ProviderNotConfigured" }, "502": { "$ref": "#/components/responses/ProviderRequestFailed" } } } }, "/v1/responses/{id}/cancel": { "post": { "summary": "Cancel OpenAI Responses run", "description": "Cancels an OpenAI Responses run through the original provider/model route. Nexus owns the upstream cancel path and resolves credentials server-side; callers send no provider credentials and no request body.", "parameters": [ { "$ref": "#/components/parameters/ResponseID" } ], "responses": { "200": { "$ref": "#/components/responses/ProxiedProviderResponse" }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ResponseNotFound" }, "500": { "$ref": "#/components/responses/InternalError" }, "501": { "$ref": "#/components/responses/ProviderNotConfigured" }, "502": { "$ref": "#/components/responses/ProviderRequestFailed" } } } }, "/v1/messages": { "post": { "summary": "Anthropic Messages-style gateway", "description": "Accepts an Anthropic Messages-style body with model and messages, resolves direct model IDs, model aliases, @preset slugs, and @route slugs, and invokes a configured Anthropic-compatible adapter. Anthropic and local Anthropic-compatible providers require messages as an array plus max_tokens as a positive integer. OpenRouter Messages models may use messages: null and may omit max_tokens; Nexus validates max_tokens as a positive integer when present. Nexus forwards only allow-listed non-secret provider request headers, including anthropic-version and anthropic-beta for Anthropic providers and HTTP-Referer, X-OpenRouter-Title, X-Title, X-OpenRouter-Categories, and X-OpenRouter-Experimental-Metadata for OpenRouter providers. Nexus validates caller-supplied anthropic-version values as YYYY-MM-DD before credential lookup, validates X-OpenRouter-Experimental-Metadata values as enabled or disabled before credential lookup, resolves upstream credentials from the local vault, forwards provider X-Request-Id/request-id response aliases when present, and strips hop-by-hop, credential-bearing, or provider CORS response headers.", "requestBody": { "$ref": "#/components/requestBodies/AnthropicMessagesRequest" }, "responses": { "200": { "$ref": "#/components/responses/ProxiedProviderResponse" }, "400": { "$ref": "#/components/responses/InvalidGatewayRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ModelNotFound" }, "500": { "$ref": "#/components/responses/InternalError" }, "501": { "$ref": "#/components/responses/ProviderNotConfigured" }, "502": { "$ref": "#/components/responses/ProviderRequestFailed" } } } }, "/v1/messages/count_tokens": { "post": { "summary": "Anthropic Messages count-token gateway", "description": "Accepts an Anthropic Messages count-token body with model and messages, resolves direct model IDs, model aliases, and @preset slugs, and invokes the provider-native Messages count-token route through a configured Anthropic-compatible adapter. Smart Route @route slugs are intentionally unsupported for token counting in the first milestone. Nexus owns the upstream sibling path after model/provider routing, rejects stream fields locally because token counting is unary, does not require or synthesize max_tokens, forwards only allow-listed non-secret provider request headers, resolves upstream credentials from the local vault, forwards provider X-Request-Id/request-id response aliases when present, and strips hop-by-hop, credential-bearing, or provider CORS response headers.", "requestBody": { "$ref": "#/components/requestBodies/AnthropicMessagesCountTokensRequest" }, "responses": { "200": { "$ref": "#/components/responses/ProxiedProviderResponse" }, "400": { "$ref": "#/components/responses/InvalidGatewayRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ModelNotFound" }, "500": { "$ref": "#/components/responses/InternalError" }, "501": { "$ref": "#/components/responses/ProviderNotConfigured" }, "502": { "$ref": "#/components/responses/ProviderRequestFailed" } } } }, "/v1/providers": { "get": { "summary": "List providers", "description": "Lists configured providers. Responses expose credentialConfigured so clients can tell whether a credential-required provider has an upstream key. Raw credential values and local credential-store references are never returned.", "responses": { "200": { "description": "Configured providers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/providers/{id}": { "get": { "summary": "Get provider", "description": "Returns one configured provider. Responses expose credentialConfigured so clients can tell whether a credential-required provider has an upstream key. Raw credential values and local credential-store references are never returned.", "parameters": [ { "$ref": "#/components/parameters/ProviderID" } ], "responses": { "200": { "description": "Configured provider.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Provider" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ProviderNotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "summary": "Create or replace provider", "description": "Stores provider metadata in SQLite and optionally stores the raw credential in the local secure credential store for credential-required provider kinds. Credential-free local runtime kinds reject credential input; rewriting an existing provider to a credential-free kind deletes any old vault entry and clears the stored reference. Changing a provider kind returns RESOURCE_IN_USE if existing models advertise endpointFamilies unsupported by the requested kind. Responses expose only credentialConfigured; raw credential values and local credential-store references are never returned. API-visible metadata rejects credential-shaped keys such as apiKey, authorization, token, and secret.", "parameters": [ { "$ref": "#/components/parameters/ProviderID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInput" } } } }, "responses": { "200": { "description": "Provider updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Provider" } } } }, "201": { "description": "Provider created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Provider" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/ResourceInUse" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "summary": "Delete provider", "description": "Deletes the provider, removes unreferenced model records owned by that provider, and removes its credential from the local credential store when a credential reference exists. If any preset references one of the provider's models, Nexus returns RESOURCE_IN_USE before touching the credential vault.", "parameters": [ { "$ref": "#/components/parameters/ProviderID" } ], "responses": { "204": { "description": "Provider deleted." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ProviderNotFound" }, "409": { "$ref": "#/components/responses/ResourceInUse" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/providers/{id}/actions": { "post": { "summary": "Run provider action", "description": "Runs side-effect-free provider diagnostics. The first action is check, which probes the provider model-list endpoint using the stored credential when required. Responses expose only stable status metadata such as credentialPresent, statusCode, and modelCount; they never include the raw credential, credential reference, upstream response body, or raw network error text.", "parameters": [ { "$ref": "#/components/parameters/ProviderID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderActionInput" } } } }, "responses": { "200": { "description": "Provider diagnostic result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderCheck" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ProviderNotFound" }, "500": { "description": "Nexus could not load provider metadata or resolve a required stored credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/runtime-discovery/scan": { "post": { "summary": "Scan local runtimes", "description": "Scans well-known loopback endpoints for local AI runtimes and OpenAI-compatible servers. The scan is best-effort, read-only, and returns only detected or already configured local endpoints with safe model previews. Nexus does not contact LAN or remote hosts during automatic discovery.", "responses": { "200": { "description": "Detected local runtime candidates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeDiscoveryScanResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/runtime-discovery/register": { "post": { "summary": "Register discovered runtime", "description": "Registers a verified loopback runtime endpoint as a local provider with autoProxyModels enabled. Registration never stores credentials, only accepts loopback base URLs, and returns an existing provider when the base URL is already configured.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeDiscoveryRegisterRequest" } } } }, "responses": { "200": { "description": "The runtime endpoint is already registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeDiscoveryRegisterResponse" } } } }, "201": { "description": "Runtime registered as a local provider.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeDiscoveryRegisterResponse" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/ResourceInUse" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/ProviderRequestFailed" } } } }, "/v1/tokens": { "get": { "summary": "List local Nexus tokens", "description": "Lists token metadata only. Raw token values and token hashes are never returned by this endpoint.", "responses": { "200": { "description": "Configured local Nexus tokens.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "summary": "Create local Nexus token", "description": "Creates a local Nexus token. The plaintext token is returned only in this creation response; later list and get calls return metadata and tokenPrefix only.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenInput" } } } }, "responses": { "201": { "description": "Token created. Save the returned plaintext token because it cannot be retrieved later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenCreateResponse" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/tokens/{id}": { "get": { "summary": "Get local Nexus token metadata", "parameters": [ { "$ref": "#/components/parameters/TokenID" } ], "responses": { "200": { "description": "Token metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Token" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/TokenNotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "summary": "Rename local Nexus token", "description": "Updates only the token display name. The plaintext token value, stored hash, tokenPrefix, scope, createdAt, and lastUsedAt remain unchanged and are never returned beyond the existing safe token metadata.", "parameters": [ { "$ref": "#/components/parameters/TokenID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenUpdateInput" } } } }, "responses": { "200": { "description": "Token metadata with the updated display name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Token" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/TokenNotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "summary": "Delete local Nexus token", "parameters": [ { "$ref": "#/components/parameters/TokenID" } ], "responses": { "204": { "description": "Token deleted." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/TokenNotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/presets": { "get": { "summary": "List parameter presets", "description": "Lists presets. The scope field is included now so local, account, and team sharing can be represented by the schema.", "responses": { "200": { "description": "Configured presets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresetList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/presets/{slug}": { "get": { "summary": "Get parameter preset", "parameters": [ { "$ref": "#/components/parameters/PresetSlug" } ], "responses": { "200": { "description": "Configured preset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Preset" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/PresetNotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "summary": "Create or replace parameter preset", "description": "Stores reusable model parameter defaults. Preset params are applied first, providerOptions second, and explicit gateway request fields last so request values override preset defaults. Stored defaults reject credential-shaped keys such as apiKey, authorization, token, and secret.", "parameters": [ { "$ref": "#/components/parameters/PresetSlug" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresetInput" } } } }, "responses": { "200": { "description": "Preset updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Preset" } } } }, "201": { "description": "Preset created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Preset" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "summary": "Delete parameter preset", "parameters": [ { "$ref": "#/components/parameters/PresetSlug" } ], "responses": { "204": { "description": "Preset deleted." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/PresetNotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/presets/{slug}/validate": { "post": { "summary": "Validate preset generation settings", "description": "Dry-runs a preset draft against its target model and reports the settings the resolved provider cannot honor. It neither reads nor writes the stored preset, so a client can check unsaved edits. The same translation runs at request time, so validation and gateway behavior cannot disagree.", "parameters": [ { "$ref": "#/components/parameters/PresetSlug" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresetInput" } } } }, "responses": { "200": { "description": "Validation completed. Warnings list what cannot be honored; an empty list means the preset is fully supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresetValidationResult" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/presets/{slug}/acceleration/actions": { "post": { "summary": "Run preset acceleration action", "description": "Runs a bounded preset acceleration action: validate, apply, or disable. Validate refreshes compatibility state, apply persists the current valid preset profile and queues a runtime restart when the owning local runtime is running, and disable turns acceleration off for this preset. Direct model calls remain unaccelerated. The response never exposes local paths, generated runtime artifacts, or raw runtime flags.", "parameters": [ { "$ref": "#/components/parameters/PresetSlug" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresetAccelerationActionInput" } } } }, "responses": { "200": { "description": "Action completed without queuing a new runtime job, or reported a safe validation/conflict result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresetAccelerationActionResult" } } } }, "202": { "description": "Action accepted and runtime restart job queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresetAccelerationActionResult" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/PresetNotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/route-packs": { "get": { "summary": "List Smart Route packs", "description": "Lists configured Smart Route packs. Enabled route packs with generation-capable fallback targets are also exposed through /v1/models as synthetic @route/{slug} models.", "responses": { "200": { "description": "Configured route packs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutePackList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/route-packs/{slug}": { "get": { "summary": "Get Smart Route pack", "parameters": [ { "$ref": "#/components/parameters/RoutePackSlug" } ], "responses": { "200": { "description": "Configured route pack.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutePack" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/RoutePackNotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "summary": "Create or replace Smart Route pack", "description": "Stores a Smart Route pack. Chat, Responses, Messages, and image-generation gateway calls to @route/{slug} ask the local router classifier to choose a route when the managed Arch router model is ready, fall back to fallbackModelId when classification is unavailable or invalid, and rewrite the upstream model field to the resolved concrete model. Image-generation requests classify from their string prompt. fallbackModelId and route targetModelId values must resolve to public generation-capable models. Image edits and non-generation sibling routes do not accept route-pack model IDs. Metadata accepts only owner, source, version, and tags as bounded non-path values.", "parameters": [ { "$ref": "#/components/parameters/RoutePackSlug" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutePackInput" } } } }, "responses": { "200": { "description": "Route pack updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutePack" } } } }, "201": { "description": "Route pack created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutePack" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "summary": "Delete Smart Route pack", "parameters": [ { "$ref": "#/components/parameters/RoutePackSlug" } ], "responses": { "204": { "description": "Route pack deleted." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/RoutePackNotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/route-packs/{slug}/actions": { "post": { "summary": "Run Smart Route pack action", "description": "Runs a route-pack action. validate returns safe validation status, warnings, and generation endpoint families.", "parameters": [ { "$ref": "#/components/parameters/RoutePackSlug" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutePackActionInput" } } } }, "responses": { "200": { "description": "Route pack action result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutePackActionResult" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/RoutePackNotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/smart-route/status": { "get": { "summary": "Get Smart Route setup status", "description": "Returns this machine's Smart Route router model status, compatible local runtime backend candidates, selected backend, and active setup job when one exists. Responses do not expose local paths, prompts, or provider credentials.", "responses": { "200": { "description": "Smart Route status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmartRouteStatus" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/smart-route/actions": { "post": { "summary": "Run Smart Route setup action", "description": "Runs a Smart Route setup action. prepare_router selects the preferred available local backend and queues the small router model download. If the selected runtime is already running another runtime or model task, the result is not accepted and uses messageKey=smartRoute.prepare.runtimeBusy while leaving routerModelStatus unchanged. If no compatible runtime is detected, Nexus returns SMART_ROUTE_NO_COMPATIBLE_RUNTIME with safe backend candidate status.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmartRouteActionInput" } } } }, "responses": { "200": { "description": "Smart Route setup was already ready or already running.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmartRouteActionResult" } } } }, "202": { "description": "Smart Route setup job accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmartRouteActionResult" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/SmartRouteNoCompatibleRuntime" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/services": { "get": { "summary": "List local runtime services", "description": "Returns stored runtime service state merged with the built-in public runtime catalog for Ollama, llama.cpp, and MLX. When runtime probing is configured, Nexus probes known local health endpoints and returns running, stopped, or unknown state with machine-readable statusProbe metadata. If Nexus has in-process evidence that a runtime process it started has exited, service reads return stopped with statusProbe.kind=managed_process_exited before making an HTTP probe and without exposing process IDs, command lines, logs, or local paths. Cataloged runtimes also include executableProbe metadata with the executable name and availability boolean from the active managed install or PATH, never the resolved local path. Platform-limited runtimes such as MLX report unsupported_platform on unsupported hosts before executable lookup or HTTP probing.", "responses": { "200": { "description": "Known local runtime services.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/services/{id}": { "get": { "summary": "Get local runtime service", "parameters": [ { "$ref": "#/components/parameters/ServiceID" } ], "responses": { "200": { "description": "Runtime service state, including executableProbe metadata and live statusProbe metadata when probing is configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Service" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ServiceNotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/services/{id}/diagnostics": { "get": { "summary": "Get service diagnostics", "description": "Returns a read-only troubleshooting view for one local runtime service. The response combines catalog defaults, endpoint families, lifecycle action support, executable availability, sanitized live status probe metadata, safe install state, and managed runtime version identifiers. It intentionally omits arbitrary service metadata, local modelsDir values, resolved executable paths, configured runtime roots, generated artifact paths, credential references, raw network errors, and upstream response bodies.", "parameters": [ { "$ref": "#/components/parameters/ServiceID" } ], "responses": { "200": { "description": "Path-safe runtime service diagnostics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceDiagnostics" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ServiceNotFound" }, "500": { "$ref": "#/components/responses/RuntimeInventoryUnavailable" } } } }, "/v1/services/{id}/update": { "get": { "summary": "Get service update state", "description": "Returns Runtime-owned update availability for one local runtime service. The response reports only safe release metadata such as current and latest version identifiers, channel, source policy, and availability booleans. App clients should use this route instead of checking upstream runtime publishers directly; service/runtime update discovery and execution remain the responsibility of Msty Nexus Runtime, while app update checks remain app responsibility. The response never includes feed URLs, manifest URLs, trusted keys, artifact URLs, local runtime roots, executable paths, raw network errors, or upstream response bodies.", "parameters": [ { "$ref": "#/components/parameters/ServiceID" } ], "responses": { "200": { "description": "Runtime-owned service update state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeUpdate" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ServiceNotFound" }, "500": { "$ref": "#/components/responses/RuntimeInventoryUnavailable" } } } }, "/v1/services/{id}/versions": { "get": { "summary": "List managed runtime versions", "description": "Lists promoted Nexus-managed runtime versions for one service. The response is read-only and contains only cataloged service IDs, runtime version strings, and an active marker derived from service metadata; it does not include the configured runtime root, executable paths, source URLs, uncataloged runtime directories, or local filesystem errors. Custom or non-managed stored services return an empty list.", "parameters": [ { "$ref": "#/components/parameters/ServiceID" } ], "responses": { "200": { "description": "Promoted managed runtime versions for the service.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeVersionList" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ServiceNotFound" }, "500": { "$ref": "#/components/responses/RuntimeInventoryUnavailable" } } } }, "/v1/services/{id}/actions": { "post": { "summary": "Queue local runtime service action", "description": "Queues install, start, stop, restart, update, rollback, or uninstall work for a supported public local runtime. Nexus stores a tracked job before execution. If another queued or running runtime/model/provider-model job already targets the same service, Nexus returns RESOURCE_IN_USE with only the conflicting job ID, kind, state, and service ID. Install and update use the configured runtime install policy. Their optional backend selects a managed accelerator variant; when omitted or automatic, Nexus chooses from backends proven ready on this host and keeps CPU as the final install fallback. The feed policy verifies one Msty-controlled signed runtime release feed, selects the allowed runtime artifact for the host, downloads the archive over HTTPS with a size bound, verifies SHA-256, stages it under the managed runtime root, promotes it atomically, records metadata.runtimeInstall, and never runs Homebrew, pip, shell installers, or other system-mutating package managers. The upstream policy remains available for publisher-direct discovery, the manifest policy uses server-side signed-manifest URLs and local trusted Ed25519 public keys, the path policy verifies preinstalled executables on PATH, and the disabled policy rejects install/update. API callers cannot submit feed URLs, manifest URLs, artifact URLs, or trust material. API callers also cannot submit model storage paths. Nexus also has release-feed and release-manifest validation, Ed25519 signed-envelope verification, exact-URL HTTPS sources, checksum verification, size-bounded HTTPS artifact download, archive planning, empty-directory extraction, staging-promotion primitives, and managed installer composition. It also enforces active-plus-five managed version retention and retained-version rollback selection. Downloaded managed install/update activates only non-running service records, clears stale PID metadata, and requires callers to stop a running service before switching the service record to a promoted runtime version. Rollback requires a retained runtimeVersion and also requires a stopped service before changing metadata.runtimeInstall. Uninstall removes Nexus-managed runtime versions and install metadata only, stops a running runtime only when this Nexus process owns it, preserves model caches and model records, and never deletes external PATH binaries. Ollama, llama.cpp, and MLX start require process survival plus readiness from the cataloged health endpoint before Nexus persists a running service; failed readiness stops the just-started process and records RUNTIME_START_FAILED job metadata. Managed stop/restart have initial executors, and exited Nexus-owned processes are reconciled without stopping external daemons. Unsupported runtime work is recorded as failed job metadata. llama.cpp starts llama-server on loopback in router mode using the configured Nexus llama.cpp models subdirectory. MLX starts msty-nexus-mlx serve on macOS loopback and is rejected with RUNTIME_ACTION_UNSUPPORTED on other hosts before executable lookup. When a port is supplied, Nexus stores a loopback service baseUrl for later status probes.", "parameters": [ { "$ref": "#/components/parameters/ServiceID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceActionRequest" } } } }, "responses": { "202": { "description": "Service action job queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ServiceNotFound" }, "409": { "$ref": "#/components/responses/ResourceInUse" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/jobs": { "get": { "summary": "List long-running jobs", "description": "Lists durable job rows. Jobs interrupted by a Nexus restart are terminal failed jobs with metadata.errorCode set to JOB_INTERRUPTED.", "responses": { "200": { "description": "Tracked jobs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "summary": "Clear terminal jobs", "description": "Deletes terminal job rows with state succeeded, failed, or cancelled. Queued and running jobs are preserved. The operation is idempotent.", "responses": { "200": { "description": "Number of terminal jobs deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobClearResult" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/jobs/{id}": { "get": { "summary": "Get long-running job", "description": "Returns one tracked job by ID so clients can poll asynchronous service and model work.", "parameters": [ { "$ref": "#/components/parameters/JobID" } ], "responses": { "200": { "description": "Tracked job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/JobNotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "summary": "Clear long-running job", "description": "Deletes one terminal job row. Queued and running jobs are preserved and return JOB_NOT_CLEARABLE.", "parameters": [ { "$ref": "#/components/parameters/JobID" } ], "responses": { "200": { "description": "Number of terminal job rows deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobClearResult" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/JobNotFound" }, "409": { "$ref": "#/components/responses/JobNotClearable" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/jobs/{id}/events": { "get": { "summary": "Stream long-running job events", "description": "Streams Server-Sent Events for one tracked job. Nexus emits the current job immediately, emits changed job snapshots while work progresses, and closes the stream after a terminal job state.", "parameters": [ { "$ref": "#/components/parameters/JobID" } ], "responses": { "200": { "description": "Server-Sent Events stream. Each event is named `job` and contains a JSON Job payload in the data field.", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/JobNotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/jobs/{id}/cancel": { "post": { "summary": "Cancel long-running job", "description": "Marks a queued or running job as cancelled and signals any in-process worker that is currently tracking the job. Completed and failed jobs return JOB_NOT_CANCELLABLE.", "parameters": [ { "$ref": "#/components/parameters/JobID" } ], "responses": { "200": { "description": "Cancelled job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/JobNotFound" }, "409": { "$ref": "#/components/responses/JobNotCancellable" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/pairing-requests": { "post": { "summary": "Create local app pairing request", "description": "Creates a short-lived pending pairing request for a local native client that does not yet have a Nexus token. It is limited to loopback requests without an Origin header. It stores no secrets; the token is created only after an authenticated Nexus client approves the request. Pairing creates local-scope tokens only. The pending queue is bounded and returns PAIRING_REQUEST_LIMIT_EXCEEDED when full.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PairingRequestInput" } } } }, "responses": { "202": { "description": "Pending pairing request created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PairingRequest" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "403": { "$ref": "#/components/responses/PairingRequestNotAllowed" }, "429": { "$ref": "#/components/responses/PairingRequestLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "get": { "summary": "List pending local app pairing requests", "description": "Lists short-lived pending pairing requests for first-party approval UIs. The response includes display name, confirmation code, local scope, and callback host/port only; it omits callback URL path/query, state, and any token material.", "responses": { "200": { "description": "Pending pairing requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PairingRequestList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/pairing-requests/{id}/approve": { "post": { "summary": "Approve local app pairing request", "description": "Approves a pending local pairing request, creates a local Nexus token, and POSTs the one-time plaintext token to the requester callback body with the original state nonce. The API response returns only redacted token metadata. If callback delivery fails, Nexus rolls back the created token and keeps the request pending for retry.", "parameters": [ { "$ref": "#/components/parameters/PairingRequestID" } ], "responses": { "200": { "description": "Pairing request approved and delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PairingDecisionResponse" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/PairingRequestNotFound" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/PairingCallbackFailed" } } } }, "/v1/pairing-requests/{id}/deny": { "post": { "summary": "Deny local app pairing request", "description": "Denies and removes a pending local pairing request without creating or delivering a token.", "parameters": [ { "$ref": "#/components/parameters/PairingRequestID" } ], "responses": { "200": { "description": "Pairing request denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PairingDecisionResponse" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/PairingRequestNotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/services/{id}/cluster/topology": { "get": { "summary": "Get distributed cluster topology", "description": "Returns the sanitized topology of the distributed MLX cluster meta-service: opaque member IDs, ranks, roles, liveness, and the active formation's mode, backend, and model. Network identifiers such as hosts, IP addresses, and RDMA device names are never returned. Services that are not the cluster meta-service return SERVICE_NOT_FOUND.", "parameters": [ { "$ref": "#/components/parameters/ServiceID" } ], "responses": { "200": { "description": "Sanitized cluster topology.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterTopology" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ServiceNotFound" } } } }, "/v1/services/{id}/cluster/discover": { "post": { "summary": "Discover the cluster fabric", "description": "Probes every online member's RDMA + Thunderbolt capability over the LAN (no SSH), assembles the jaccl mesh, and records it for a later form. Returns a sanitized readiness report: opaque member IDs, per-node RDMA state and Thunderbolt links, and whether the set forms a complete, formable mesh. It exposes no IP addresses, hostnames, RDMA device names, or Thunderbolt UUIDs. Returns 409 when there are no online members and 503 when fabric discovery is not available on this runtime. Services that are not the cluster meta-service return SERVICE_NOT_FOUND.", "parameters": [ { "$ref": "#/components/parameters/ServiceID" } ], "responses": { "200": { "description": "Sanitized cluster fabric discovery report.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterDiscovery" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ServiceNotFound" }, "409": { "$ref": "#/components/responses/ResourceInUse" } } } }, "/v1/services/{id}/cluster/configure-links": { "post": { "summary": "Configure the cluster's Thunderbolt-IP links", "description": "Pushes each member its computed Thunderbolt-IP link plan (from the most recent discover) so each machine's root link helper brings the RDMA links up \u2014 the no-SSH replacement for mlx.distributed_config --auto-setup. Returns 409 before discover has run and 503 when membership is not editable on this runtime. Services that are not the cluster meta-service return SERVICE_NOT_FOUND.", "parameters": [ { "$ref": "#/components/parameters/ServiceID" } ], "responses": { "200": { "description": "Link configuration was dispatched to the members.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ServiceNotFound" }, "409": { "$ref": "#/components/responses/ResourceInUse" } } } }, "/v1/services/{id}/cluster/links": { "post": { "summary": "Apply this member's Thunderbolt-IP link plan", "description": "Writes this member's validated link plan to the file its root link helper watches, bringing the RDMA links up. This is an internal Runtime-to-Runtime call on the no-SSH link-setup path; the member re-validates every entry so the privileged helper only ever sees well-formed ifconfig/route steps. Returns 503 when link configuration is not available on this runtime. Services that are not the cluster meta-service return SERVICE_NOT_FOUND.", "parameters": [ { "$ref": "#/components/parameters/ServiceID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ClusterLinkCommand" } } } } }, "responses": { "200": { "description": "The link plan was written for the local helper.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ServiceNotFound" } } } }, "/v1/services/{id}/cluster/members": { "get": { "summary": "List configured cluster machines", "description": "Returns the cluster machines the operator has configured (from the app or MSTY_NEXUS_CLUSTER_MEMBERS). Unlike the public topology, this operator-facing management surface includes the host the operator entered, like a provider base URL, so the app can list and edit machines. Services that are not the cluster meta-service return SERVICE_NOT_FOUND.", "parameters": [ { "$ref": "#/components/parameters/ServiceID" } ], "responses": { "200": { "description": "Configured cluster machines.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterMembers" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ServiceNotFound" } } }, "post": { "summary": "Add a cluster machine", "description": "Registers a cluster machine by hostname or IP literal and Runtime port; the server assigns the opaque member ID and derives the control URL, then persists the member so it survives a controller restart. The host field must not include a scheme, path, query string, credentials, or port. Returns 503 when membership is not editable on this runtime. Services that are not the cluster meta-service return SERVICE_NOT_FOUND.", "parameters": [ { "$ref": "#/components/parameters/ServiceID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterAddMember" } } } }, "responses": { "200": { "description": "The stored cluster machine.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterMember" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ServiceNotFound" } } } }, "/v1/services/{id}/cluster/members/{memberId}": { "delete": { "summary": "Remove a cluster machine", "description": "Drops a configured cluster machine by its member ID and persists the change. Returns 404 when the member is unknown. Services that are not the cluster meta-service return SERVICE_NOT_FOUND.", "parameters": [ { "$ref": "#/components/parameters/ServiceID" }, { "name": "memberId", "in": "path", "required": true, "description": "Opaque cluster member ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The cluster machine was removed.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ServiceNotFound" } } } }, "/v1/services/{id}/cluster/provision": { "post": { "summary": "Queue cluster provisioning (install MLX on every member)", "description": "Queues MLX runtime installation on every cluster member so a subsequent Form can launch workers \u2014 a freshly-joined node has only the Nexus runtime. The returned job is the durable progress and cancellation handle. Provisioning can run alongside cluster model preparation, but another active provisioning job for the same cluster is rejected with RESOURCE_IN_USE. Services that are not the cluster meta-service return SERVICE_NOT_FOUND.", "parameters": [ { "$ref": "#/components/parameters/ServiceID" } ], "responses": { "202": { "description": "Cluster provisioning job queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ServiceNotFound" }, "409": { "$ref": "#/components/responses/ResourceInUse" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/services/{id}/cluster/prepare-model": { "post": { "summary": "Queue cluster model preparation on every member", "description": "Queues a pull of the selected Hugging Face MLX model snapshot into every cluster member's Nexus-managed MLX cache before Form launches workers. Cached files are reused, so the route is safe to call before every formation. The returned job is the durable progress and cancellation handle. Model preparation can run alongside cluster provisioning, but another active model preparation job for the same cluster is rejected with RESOURCE_IN_USE. The model must be an owner/repo-style, path-safe Hugging Face model ID with no leading or trailing whitespace. Services that are not the cluster meta-service return SERVICE_NOT_FOUND.", "parameters": [ { "$ref": "#/components/parameters/ServiceID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterPrepareModel" } } } }, "responses": { "202": { "description": "Cluster model preparation job queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ServiceNotFound" }, "409": { "$ref": "#/components/responses/ResourceInUse" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/services/{id}/cluster/join-tokens": { "post": { "summary": "Mint a cluster join token", "description": "Mints a short-lived join token the operator carries to new nodes so they self-enroll without any baked secret \u2014 the engine behind the app's Create cluster one-liner. The response also includes the matching hosted setup script URL for the controller's selected cluster asset channel. Returns 503 when membership is not editable on this runtime and 409 when too many join tokens are active. Services that are not the cluster meta-service return SERVICE_NOT_FOUND.", "parameters": [ { "$ref": "#/components/parameters/ServiceID" } ], "responses": { "200": { "description": "A freshly minted join token, its expiry, and the matching setup script URL.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "token", "expiresAt" ], "properties": { "object": { "type": "string", "const": "msty.nexus.cluster_join_token" }, "token": { "type": "string", "description": "Short-lived plaintext join token returned once for the operator-created command." }, "expiresAt": { "type": "string", "format": "date-time" }, "setupUrl": { "type": "string", "format": "uri", "description": "Hosted setup.sh URL matching the controller's selected cluster asset channel." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ServiceNotFound" }, "409": { "$ref": "#/components/responses/ResourceInUse" }, "503": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "summary": "Revoke active cluster join tokens", "description": "Invalidates every active cluster join token on the controller. The Runtime stores only token hashes and never lists plaintext commands, so this clears the active join-command window for recovery when token creation returns CLUSTER_JOIN_TOKEN_LIMIT_EXCEEDED. Services that are not the cluster meta-service return SERVICE_NOT_FOUND.", "parameters": [ { "$ref": "#/components/parameters/ServiceID" } ], "responses": { "200": { "description": "The active join-token window was cleared.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ServiceNotFound" }, "503": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/services/{id}/cluster/join": { "post": { "summary": "Join a cluster with a join token", "description": "Enrolls a node that presents a valid join token. Unauthenticated: a new node has no Nexus token yet, so the short-lived join token in the body authorizes the call. The node registers its own per-node credential, which authenticates every later controller call to it. Reruns may include the previously assigned memberId so the controller refreshes the same member after reinstall or address changes. Returns 403 when the join token is invalid or expired and SERVICE_NOT_FOUND for a non-cluster service.", "security": [], "parameters": [ { "$ref": "#/components/parameters/ServiceID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token", "host", "port", "nodeToken" ], "properties": { "token": { "type": "string", "description": "Short-lived join token minted by the controller." }, "memberId": { "type": "string", "description": "Optional previously assigned opaque member ID. The generated join script sends this on reruns so the controller refreshes the same member." }, "host": { "type": "string", "description": "LAN hostname or IP literal the controller should use to reach this node. Do not include a scheme, path, query string, credentials, or port." }, "port": { "type": "integer", "description": "Runtime API port on this node.", "minimum": 1, "maximum": 65535 }, "nodeToken": { "type": "string", "description": "Per-node Nexus credential that authenticates later controller-to-node calls." } } } } } }, "responses": { "200": { "description": "The node joined the cluster.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ServiceNotFound" } } } }, "/v1/services/{id}/cluster/join.sh": { "get": { "summary": "Download the cluster join script", "description": "Returns the bootstrap shell script a new node runs (curl ... | sudo bash) to download the generic runtime, install it, and enroll using the join token. Unauthenticated but gated by the join token in the ?token query string; returns 403 when the token is invalid or expired. The script is generated per request and calls back to this controller.", "security": [], "parameters": [ { "$ref": "#/components/parameters/ServiceID" }, { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The short-lived join token authorizing the download." } ], "responses": { "200": { "description": "The bootstrap shell script.", "content": { "text/x-shellscript": { "schema": { "type": "string" } } } }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ServiceNotFound" } } } }, "/v1/services/{id}/cluster/node-capability": { "get": { "summary": "Get this member's cluster-fabric capability", "description": "Reports this Runtime's own RDMA (ibverbs) devices and Thunderbolt wiring so the controller can assemble the jaccl mesh over the LAN without SSH. Part of the internal Runtime-to-Runtime discovery path; it carries device and port identifiers the controller needs, never controller secrets, and is never the public host-free topology. Returns 503 when capability probing is not available on this runtime. Services that are not the cluster meta-service return SERVICE_NOT_FOUND.", "parameters": [ { "$ref": "#/components/parameters/ServiceID" } ], "responses": { "200": { "description": "This member's RDMA and Thunderbolt capability.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterNodeCapability" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ServiceNotFound" } } } }, "/v1/services/{id}/cluster/worker/status": { "get": { "summary": "Get this member's cluster worker status", "description": "Reports whether this Runtime's local MLX cluster worker is running, with its model and rank. Part of the internal Runtime-to-Runtime launch path the controller drives over the LAN; status stays available even when worker launching is disabled. Services that are not the cluster meta-service return SERVICE_NOT_FOUND.", "parameters": [ { "$ref": "#/components/parameters/ServiceID" } ], "responses": { "200": { "description": "Worker status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterWorkerState" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ServiceNotFound" } } } }, "/v1/services/{id}/cluster/worker/start": { "post": { "summary": "Start this member's cluster worker", "description": "Launches this Runtime's local MLX worker for a formation from the rank spec the controller sends. This is an internal Runtime-to-Runtime call on the no-SSH launch path; the spec carries only rank wiring (model, ports, env, RDMA device matrix), never controller secrets. Returns 503 when worker launching is not available on this runtime.", "parameters": [ { "$ref": "#/components/parameters/ServiceID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterWorkerSpec" } } } }, "responses": { "200": { "description": "Worker started; current status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterWorkerState" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ServiceNotFound" }, "503": { "description": "Worker launching is not available on this runtime.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/services/{id}/cluster/worker/stop": { "post": { "summary": "Stop this member's cluster worker", "description": "Stops this Runtime's local MLX worker. Internal Runtime-to-Runtime call on the no-SSH launch path. Returns 503 when worker launching is not available on this runtime.", "parameters": [ { "$ref": "#/components/parameters/ServiceID" } ], "responses": { "200": { "description": "Worker stopped; current status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterWorkerState" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ServiceNotFound" }, "503": { "description": "Worker launching is not available on this runtime.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/services/{id}/cluster/form": { "post": { "summary": "Form a distributed cluster", "description": "Forms the distributed MLX cluster from the currently online members, pinning the requested coordinator to rank 0. Form requires a latest discovery report whose fabric is formable; when the Thunderbolt mesh is cabled but at least one member still needs RDMA enabled, the request returns CLUSTER_FABRIC_NOT_READY. Worker launching is gated by the runtime: when the worker launcher is unavailable the request returns 503. Nexus waits for the coordinator model API before recording the formation; if the workers start but the model server does not become ready, the request returns CLUSTER_COORDINATOR_NOT_READY. After successful formation, Nexus stores a private rank-0 /v1 route for gateway routing and automatically queues a cluster model sync job so the served model appears as cluster/. Inter-rank and API ports are server-owned and are never accepted from the client.", "parameters": [ { "$ref": "#/components/parameters/ServiceID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mode", "model", "coordinatorId" ], "properties": { "mode": { "type": "string", "enum": [ "pipeline", "tensor" ] }, "model": { "type": "string", "description": "Nexus model ID to serve across the cluster. Must not include leading or trailing whitespace.", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:\\[\\]-]*(/[A-Za-z0-9][A-Za-z0-9._:\\[\\]-]*)*$" }, "coordinatorId": { "type": "string", "description": "Cluster member ID to pin to rank 0. Must not include leading or trailing whitespace." } } } } } }, "responses": { "200": { "description": "Cluster formed; returns the sanitized topology.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterTopology" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ServiceNotFound" }, "409": { "description": "The cluster is already formed or the coordinator is not an online member.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Cluster worker launching is not available on this runtime.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/services/{id}/cluster/launch": { "post": { "summary": "Launch a distributed cluster", "description": "Queues distributed MLX cluster formation as a durable job and returns immediately with a progress/cancellation handle. This is the preferred operation for app and admin clients because worker startup waits for rank 0's model API and can take longer than a foreground request timeout. Launch uses the same validation and server-owned ports as cluster form. It conflicts with active cluster setup jobs so MLX preparation, model preparation, and worker startup do not overlap.", "parameters": [ { "$ref": "#/components/parameters/ServiceID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mode", "model", "coordinatorId" ], "properties": { "mode": { "type": "string", "enum": [ "pipeline", "tensor" ] }, "model": { "type": "string", "description": "Nexus model ID to serve across the cluster. Must not include leading or trailing whitespace.", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:\\[\\]-]*(/[A-Za-z0-9][A-Za-z0-9._:\\[\\]-]*)*$" }, "coordinatorId": { "type": "string", "description": "Cluster member ID to pin to rank 0. Must not include leading or trailing whitespace." } } } } } }, "responses": { "202": { "description": "Cluster launch queued; returns the job tracking worker startup and readiness.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ServiceNotFound" }, "409": { "description": "Another cluster setup job is already active, the cluster is already formed, or the coordinator is not an online member.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Cluster worker launching is not available on this runtime.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/services/{id}/cluster/leave": { "post": { "summary": "Leave a distributed cluster", "description": "Tears down the active cluster formation, stopping every member's worker. A successful leave clears the private rank-0 route, disables the cluster provider, and hides synced cluster/ records until the next successful Form and sync. Returns 409 when no formation is active.", "parameters": [ { "$ref": "#/components/parameters/ServiceID" } ], "responses": { "200": { "description": "Cluster formation torn down. The response body is a confirmation object with no fields clients are expected to read.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ServiceNotFound" }, "409": { "description": "The cluster is not formed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/services/{id}/accounts": { "get": { "summary": "List connected service accounts", "description": "Lists the subscription accounts connected to an account-capable runtime such as cliproxy. Records are redacted projections of the runtime's stored credential files: ID, best-effort provider classification, and an optional display label. Token material, refresh tokens, the runtime management secret, and local filesystem paths are never returned. The service must be running; account state lives behind its loopback management surface. Services without an account surface return SERVICE_NOT_FOUND.", "parameters": [ { "$ref": "#/components/parameters/ServiceID" } ], "responses": { "200": { "description": "Connected accounts for the service.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceAccountList" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ServiceNotFound" }, "409": { "description": "Service is not running, so its management surface is unreachable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "The runtime management surface rejected or failed the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/services/{id}/accounts/{accountId}": { "delete": { "summary": "Remove a connected service account", "description": "Removes one connected account by its redacted record ID. The ID must be a single path-safe file name; separators and traversal segments are rejected. Removal deletes only the runtime's stored credential file, records a service.account_removed audit event without the account ID (file names may embed an email address), and queues a model sync so catalog rows from the removed account are pruned.", "parameters": [ { "$ref": "#/components/parameters/ServiceID" }, { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connected account record ID from the accounts list." } ], "responses": { "204": { "description": "The connected account was removed." }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ServiceNotFound" }, "409": { "description": "Service is not running, so its management surface is unreachable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "The runtime management surface rejected or failed the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/services/{id}/accounts/logins": { "post": { "summary": "Start an account sign-in flow", "description": "Starts an OAuth sign-in flow for one subscription account provider on an account-capable runtime. The response contains the provider authorization URL the user must open in a browser and an opaque loginId for polling completion. Nexus proxies the runtime's loopback management API with a Nexus-generated management secret that is never returned to API clients.", "parameters": [ { "$ref": "#/components/parameters/ServiceID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceAccountLoginRequest" } } } }, "responses": { "200": { "description": "The sign-in flow was started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceAccountLogin" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ServiceNotFound" }, "409": { "description": "Service is not running, so its management surface is unreachable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "The runtime management surface rejected or failed the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/services/{id}/accounts/logins/{loginId}": { "get": { "summary": "Poll an account sign-in flow", "description": "Reports whether a started sign-in flow is pending, completed, or failed. On the first successful completion poll, Nexus records a service.account_added audit event and queues a model sync job (returned as syncJobId) so the catalog reflects the newly connected account.", "parameters": [ { "$ref": "#/components/parameters/ServiceID" }, { "name": "loginId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Opaque sign-in flow handle returned when the flow was started." } ], "responses": { "200": { "description": "Current sign-in flow state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceAccountLogin" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ServiceNotFound" }, "409": { "description": "Service is not running, so its management surface is unreachable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "The runtime management surface rejected or failed the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Local Nexus token sent as Authorization: Bearer ." }, "nexusTokenHeader": { "type": "apiKey", "in": "header", "name": "X-Msty-Nexus-Token", "description": "Local Nexus token sent as X-Msty-Nexus-Token." }, "anthropicApiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Local Nexus token sent through Anthropic-compatible x-api-key. Nexus replaces this before contacting upstream Anthropic providers." } }, "parameters": { "ProviderID": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" } }, "ModelID": { "name": "id", "in": "path", "required": true, "description": "Slash-separated Nexus model ID captured by the server wildcard route, for example openai/gpt-test. Clients may send raw slash paths or percent-encoded slashes such as openai%2Fgpt-test.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:\\[\\]-]*(/[A-Za-z0-9][A-Za-z0-9._:\\[\\]-]*)*$" } }, "ResponseID": { "name": "id", "in": "path", "required": true, "description": "OpenAI Responses ID previously indexed by Nexus from a successful non-streaming create response.", "schema": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[!-.0-~]+$" } }, "PresetSlug": { "name": "slug", "in": "path", "required": true, "description": "Human-readable preset slug used in @preset/ gateway model references.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" } }, "RoutePackSlug": { "name": "slug", "in": "path", "required": true, "description": "Human-readable Smart Route pack slug used in @route/ gateway model references.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" } }, "TokenID": { "name": "id", "in": "path", "required": true, "description": "Local Nexus token record ID.", "schema": { "type": "string", "pattern": "^tok_[A-Za-z0-9_-]{8,128}$" } }, "ServiceID": { "name": "id", "in": "path", "required": true, "description": "Runtime service ID, for example ollama, llamacpp, or mlx.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" } }, "JobID": { "name": "id", "in": "path", "required": true, "description": "Long-running job ID returned by a mutating control-plane request.", "schema": { "type": "string", "pattern": "^job-[A-Za-z0-9_-]{1,128}$" } }, "PairingRequestID": { "name": "id", "in": "path", "required": true, "description": "Pending local pairing request ID.", "schema": { "type": "string", "pattern": "^pair_[A-Za-z0-9_-]{16,128}$" } } }, "requestBodies": { "OpenAIChatCompletionsRequest": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIChatCompletionsRequest" } } } }, "OpenAIEmbeddingsRequest": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIEmbeddingsRequest" } } } }, "OpenAIResponsesRequest": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIResponsesRequest" } } } }, "OpenAIResponsesInputTokensRequest": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIResponsesInputTokensRequest" } } } }, "OpenAIResponsesCompactRequest": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIResponsesCompactRequest" } } } }, "AnthropicMessagesRequest": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessagesRequest" } } } }, "AnthropicMessagesCountTokensRequest": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessagesCountTokensRequest" } } } } }, "responses": { "Unauthorized": { "description": "The request did not include a valid local Nexus token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "InvalidGatewayRequest": { "description": "The request body was invalid JSON, was not an object, omitted required gateway fields, or selected a model that does not support this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "InvalidRequest": { "description": "The request body or path parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "GaugeAlertRuleNotFound": { "description": "The requested local Gauge alert rule does not exist.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}}} }, "GaugeAlertEventNotFound": { "description": "The requested local Gauge alert event does not exist.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}}} }, "GaugeBudgetNotFound": { "description": "The requested local Gauge project budget does not exist.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}}} }, "GaugeAuthSessionNotFound": { "description": "The requested ephemeral Gauge authentication session does not exist.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}}} }, "ModelNotFound": { "description": "The requested model or preset could not be resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "ResponseNotFound": { "description": "The requested OpenAI Responses route could not be resolved from the local non-secret response-route index.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "ProviderNotFound": { "description": "The requested provider could not be resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "PresetNotFound": { "description": "The requested preset could not be resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "RoutePackNotFound": { "description": "The requested Smart Route pack could not be resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "SmartRouteNoCompatibleRuntime": { "description": "No compatible local runtime was detected for Smart Route setup.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "ServiceNotFound": { "description": "The requested runtime service could not be resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "JobNotFound": { "description": "The requested long-running job could not be resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "JobNotCancellable": { "description": "The requested long-running job is already finished and cannot be cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "JobNotClearable": { "description": "The requested long-running job is still active and cannot be cleared.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "ResourceInUse": { "description": "The requested resource is still referenced by another configured resource or an active job already owns the requested mutation target.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "TokenNotFound": { "description": "The requested local token record could not be resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "ProviderNotConfigured": { "description": "The model resolved, but no provider adapter is configured yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "ProviderRequestFailed": { "description": "The configured provider adapter could not complete the upstream request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "ModelRegistryRequestFailed": { "description": "Every requested external model registry source failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "ProxiedProviderResponse": { "description": "Raw upstream provider response proxied by Msty Nexus.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/event-stream": { "schema": { "type": "string" } } } }, "MultipartRequestTooLarge": { "description": "The multipart request exceeded the 268435456-byte gateway upload limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "CredentialStoreError": { "description": "The local credential store could not store, load, or delete a provider credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "RuntimeInventoryUnavailable": { "description": "The configured managed runtime inventory could not be inspected safely. The response uses a stable code and omits local paths and filesystem details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "InternalError": { "description": "An internal error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "PairingRequestNotAllowed": { "description": "The pairing request was not accepted because it did not come from a loopback native client or included a browser Origin header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "PairingRequestNotFound": { "description": "The pending local pairing request was not found or has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "PairingCallbackFailed": { "description": "The user approved the pairing request, but Nexus could not deliver the token to the loopback callback. When rollback succeeds, the request remains pending so approval can be retried.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "PairingRequestLimitExceeded": { "description": "The pending local pairing request queue is full. Retry after existing requests expire or are approved or denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "schemas": { "HealthResponse": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "const": "ok" } } }, "VersionInfo": { "type": "object", "required": [ "object", "name", "version", "commit", "buildDate", "goVersion", "platform" ], "properties": { "object": { "type": "string", "const": "msty.nexus.version" }, "name": { "type": "string", "const": "msty-nexus" }, "version": { "type": "string" }, "commit": { "type": "string" }, "buildDate": { "type": "string" }, "goVersion": { "type": "string" }, "platform": { "type": "string" } }, "additionalProperties": false }, "Settings": { "type": "object", "description": "Operational settings for the running Nexus process. The schema intentionally omits local tokens, database paths, runtime roots, generated artifact paths, credential references, and provider credentials while exposing the user-configurable local models directory and local runtime tuning.", "required": [ "object", "bind", "cors", "runtime", "diagnostics", "usage", "gauge" ], "properties": { "object": { "type": "string", "const": "msty.nexus.settings" }, "bind": { "$ref": "#/components/schemas/SettingsBind" }, "cors": { "$ref": "#/components/schemas/SettingsCORS" }, "runtime": { "$ref": "#/components/schemas/SettingsRuntime" }, "diagnostics": { "$ref": "#/components/schemas/SettingsDiagnostics" }, "usage": { "$ref": "#/components/schemas/SettingsUsage" }, "gauge": { "$ref": "#/components/schemas/SettingsGauge" } }, "additionalProperties": false }, "SettingsBind": { "type": "object", "required": [ "host", "port", "networkExposed" ], "properties": { "host": { "type": "string" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "networkExposed": { "type": "boolean" }, "pendingHost": { "type": "string", "description": "Pending bind host that will become effective after Runtime restarts." }, "pendingNetworkExposed": { "type": "boolean", "description": "Pending network exposure posture that will become effective after Runtime restarts." }, "restartRequired": { "type": "boolean", "description": "True when persisted bind intent differs from the running listener." } }, "additionalProperties": false }, "SettingsCORS": { "type": "object", "description": "Effective origin policy for direct local web and supported app clients. A wildcard origin cannot be combined with explicit origins.", "required": [ "enabled", "allowedOrigins" ], "properties": { "enabled": { "type": "boolean", "description": "Whether this provider participates in model discovery, provider model sync, and gateway routing. Disabled providers remain configured but their models and presets are hidden from /v1/models." }, "allowedOrigins": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "SettingsPatch": { "type": "object", "description": "Partial settings mutation. bind.networkExposed is the only writable listener setting; it stores local-only versus network-exposed intent and requires Runtime restart when it differs from the active bind. cors.allowedOrigins is applied to the running CORS middleware immediately. runtime.modelsDirectory changes the single local models root used for Nexus-managed model storage. runtime.tuning changes local runtime resource behavior and uses 0 for automatic defaults. diagnostics.gatewayRequestLoggingEnabled toggles local gateway metadata logging without logging request bodies, prompt text, response text, headers, credentials, or provider secrets. Listener host strings, ports, runtime roots, artifact paths, tokens, and credentials remain server-side configuration. usage.trackingEnabled toggles local usage-metrics capture and usage.retentionDays bounds how long raw usage events are retained. gauge.enabled opts into cross-provider Gauge collection and gauge.retentionDays bounds its normalized history.", "minProperties": 1, "properties": { "bind": { "$ref": "#/components/schemas/SettingsBindPatch" }, "cors": { "$ref": "#/components/schemas/SettingsCORSPatch" }, "runtime": { "$ref": "#/components/schemas/SettingsRuntimePatch" }, "diagnostics": { "$ref": "#/components/schemas/SettingsDiagnosticsPatch" }, "usage": { "$ref": "#/components/schemas/SettingsUsagePatch" }, "gauge": { "$ref": "#/components/schemas/SettingsGaugePatch" } }, "additionalProperties": false }, "SettingsBindPatch": { "type": "object", "description": "Durable listener exposure update. true maps to a network listener on the next Runtime start; false maps to local-only loopback. Callers cannot choose arbitrary bind hosts or ports.", "required": [ "networkExposed" ], "properties": { "networkExposed": { "type": "boolean" } }, "additionalProperties": false }, "SettingsCORSPatch": { "type": "object", "description": "Durable CORS allow-list update. Empty allowedOrigins disables origin access. Values must be '*', http/https origins, or supported local app origins such as tauri://localhost, without credentials, paths, queries, or fragments.", "required": [ "allowedOrigins" ], "properties": { "allowedOrigins": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "SettingsRuntime": { "type": "object", "required": [ "managedRootConfigured", "modelCacheConfigured", "modelsDirectory", "installPolicy", "pathBasedInstallEnabled", "downloadedInstallsEnabled", "managedVersionListingEnabled", "tuning" ], "properties": { "managedRootConfigured": { "type": "boolean" }, "modelCacheConfigured": { "type": "boolean", "description": "True when Nexus has a server-side managed model cache root configured." }, "modelsDirectory": { "type": "string", "description": "Effective local directory used as the single root for Nexus-managed model storage. By default, Nexus uses the current OS user's .msty-nexus/models directory. The response reports a resolved absolute filesystem path, and runtime-specific files live under subdirectories such as ollama, llamacpp, and mlx." }, "installPolicy": { "type": "string", "enum": [ "upstream", "feed", "manifest", "path", "disabled" ], "description": "Effective runtime install/update source policy." }, "pathBasedInstallEnabled": { "type": "boolean", "description": "True only when the effective install policy is path." }, "downloadedInstallsEnabled": { "type": "boolean", "description": "True when the effective install policy downloads managed runtime archives through upstream or manifest sources." }, "managedVersionListingEnabled": { "type": "boolean" }, "tuning": { "$ref": "#/components/schemas/RuntimeTuningSettings" } }, "additionalProperties": false }, "RuntimeTuningSettings": { "type": "object", "description": "Durable local runtime tuning. Integer value 0 means Nexus leaves that setting on the runtime's automatic default.", "required": [ "ollama", "llamacpp", "mlx" ], "properties": { "ollama": { "$ref": "#/components/schemas/OllamaRuntimeTuning" }, "llamacpp": { "$ref": "#/components/schemas/LlamaCppRuntimeTuning" }, "mlx": { "$ref": "#/components/schemas/MLXRuntimeTuning" } }, "additionalProperties": false }, "OllamaRuntimeTuning": { "type": "object", "required": [ "contextLength", "parallelRequests", "maxLoadedModels", "maxQueue", "keepAliveMinutes" ], "properties": { "contextLength": { "type": "integer", "minimum": 0, "description": "Context window tokens for new Ollama requests. 0 uses Ollama automatic defaults." }, "parallelRequests": { "type": "integer", "minimum": 0, "description": "Parallel Ollama request slots. 0 uses Ollama automatic defaults." }, "maxLoadedModels": { "type": "integer", "minimum": 0, "description": "Maximum loaded Ollama models. 0 uses Ollama automatic defaults." }, "maxQueue": { "type": "integer", "minimum": 0, "description": "Maximum queued Ollama requests. 0 uses Ollama automatic defaults." }, "keepAliveMinutes": { "type": "integer", "minimum": 0, "description": "Minutes Ollama keeps models ready after use. 0 uses Ollama automatic defaults." } }, "additionalProperties": false }, "LlamaCppRuntimeTuning": { "type": "object", "required": [ "contextLength", "parallelRequests", "threads", "batchSize", "microBatchSize" ], "properties": { "contextLength": { "type": "integer", "minimum": 0, "description": "Context window tokens for llama.cpp. 0 uses llama.cpp automatic defaults." }, "parallelRequests": { "type": "integer", "minimum": 0, "description": "Parallel llama.cpp request slots. 0 uses llama.cpp automatic defaults." }, "threads": { "type": "integer", "minimum": 0, "description": "CPU threads for llama.cpp. 0 uses llama.cpp automatic defaults." }, "batchSize": { "type": "integer", "minimum": 0, "description": "llama.cpp batch size. 0 uses llama.cpp automatic defaults." }, "microBatchSize": { "type": "integer", "minimum": 0, "description": "llama.cpp micro-batch size. 0 uses llama.cpp automatic defaults." } }, "additionalProperties": false }, "MLXRuntimeTuning": { "type": "object", "description": "Reserved for future MLX tuning. MLX uses automatic settings in this version.", "additionalProperties": false }, "SettingsRuntimePatch": { "type": "object", "description": "Durable local runtime settings update. modelsDirectory values must be absolute filesystem paths. New runtime starts and model actions use runtime-specific subdirectories under this root. tuning changes local runtime resource behavior and uses 0 for automatic defaults.", "minProperties": 1, "properties": { "modelsDirectory": { "type": "string", "minLength": 1 }, "tuning": { "$ref": "#/components/schemas/SettingsRuntimeTuningPatch" } }, "additionalProperties": false }, "SettingsRuntimeTuningPatch": { "type": "object", "description": "Partial local runtime tuning update. Include ollama, llamacpp, or both.", "minProperties": 1, "properties": { "ollama": { "$ref": "#/components/schemas/OllamaRuntimeTuningPatch" }, "llamacpp": { "$ref": "#/components/schemas/LlamaCppRuntimeTuningPatch" } }, "additionalProperties": false }, "OllamaRuntimeTuningPatch": { "type": "object", "minProperties": 1, "properties": { "contextLength": { "type": "integer", "minimum": 0, "maximum": 262144 }, "parallelRequests": { "type": "integer", "minimum": 0, "maximum": 16 }, "maxLoadedModels": { "type": "integer", "minimum": 0, "maximum": 16 }, "maxQueue": { "type": "integer", "minimum": 0, "maximum": 1024 }, "keepAliveMinutes": { "type": "integer", "minimum": 0, "maximum": 1440 } }, "additionalProperties": false }, "LlamaCppRuntimeTuningPatch": { "type": "object", "minProperties": 1, "properties": { "contextLength": { "type": "integer", "minimum": 0, "maximum": 262144 }, "parallelRequests": { "type": "integer", "minimum": 0, "maximum": 16 }, "threads": { "type": "integer", "minimum": 0, "maximum": 128 }, "batchSize": { "type": "integer", "minimum": 0, "maximum": 8192 }, "microBatchSize": { "type": "integer", "minimum": 0, "maximum": 4096 } }, "additionalProperties": false }, "SettingsDiagnostics": { "type": "object", "description": "Opt-in local troubleshooting settings. Gateway request logging records metadata such as model, provider, route, selected parameters, status, and duration; it never records request bodies, prompt text, response text, headers, credentials, or provider secrets.", "required": [ "gatewayRequestLoggingEnabled" ], "properties": { "gatewayRequestLoggingEnabled": { "type": "boolean", "description": "True when local gateway metadata logging is enabled." } }, "additionalProperties": false }, "SettingsDiagnosticsPatch": { "type": "object", "description": "Durable diagnostics settings update. Include gatewayRequestLoggingEnabled to enable or disable gateway metadata logs without logging request bodies, prompt text, response text, headers, credentials, or provider secrets.", "required": [ "gatewayRequestLoggingEnabled" ], "properties": { "gatewayRequestLoggingEnabled": { "type": "boolean" } }, "additionalProperties": false }, "HardwareTelemetry": { "type": "object", "description": "Authenticated public-safe host and accelerator telemetry for model-fit decisions. Device names may be present so users can identify the relevant GPU; serials, UUIDs, PCI addresses, local paths, runtime roots, provider records, credentials, and local Nexus token values are omitted.", "required": [ "object", "generatedAt", "host" ], "properties": { "object": { "type": "string", "const": "msty.nexus.hardware_telemetry" }, "generatedAt": { "type": "string", "format": "date-time" }, "host": { "$ref": "#/components/schemas/HardwareHostTelemetry" }, "devices": { "type": "array", "items": { "$ref": "#/components/schemas/HardwareDeviceTelemetry" } }, "problems": { "type": "array", "items": { "$ref": "#/components/schemas/HardwareTelemetryProblem" } } }, "additionalProperties": false }, "HardwareHostTelemetry": { "type": "object", "description": "Host-level hardware facts used for local model-fit estimates.", "required": [ "os", "arch" ], "properties": { "os": { "type": "string", "description": "Runtime host operating system using GOOS values such as darwin, linux, or windows." }, "arch": { "type": "string", "description": "Runtime host architecture using GOARCH values such as arm64 or amd64." }, "logicalCpuCount": { "type": "integer", "minimum": 0 }, "totalMemoryBytes": { "type": "integer", "format": "int64", "minimum": 0 }, "availableMemoryBytes": { "type": "integer", "format": "int64", "minimum": 0 }, "availableMemoryConfidence": { "type": "string", "enum": [ "reported", "estimated", "unknown" ] } }, "additionalProperties": false }, "HardwareDeviceTelemetry": { "type": "object", "description": "Public-safe accelerator summary. When Nexus can access its OS credential store, IDs are opaque identifiers that remain stable within this Nexus installation. They are not hardware serials, UUIDs, PCI paths, or portable machine identifiers. If stable identity is unavailable, the response includes GPU_IDENTITY_UNAVAILABLE and IDs are response-local.", "required": [ "id", "kind" ], "properties": { "id": { "type": "string", "description": "Opaque installation-local device ID, or a response-local gpu-N fallback when GPU_IDENTITY_UNAVAILABLE is reported." }, "kind": { "type": "string", "enum": [ "gpu" ] }, "name": { "type": "string" }, "vendor": { "type": "string" }, "backend": { "type": "string", "description": "Preferred ready accelerator backend such as metal, cuda, rocm, vulkan, or sycl. Omitted when no backend has been proven usable." }, "availableBackends": { "type": "array", "description": "Backends that passed a vendor-aware readiness probe for this device.", "items": { "type": "string" } }, "readiness": { "type": "string", "enum": [ "ready", "limited", "unavailable", "unknown" ] }, "driverStatus": { "type": "string", "enum": [ "ready", "unavailable", "unknown" ] }, "driverVersion": { "type": "string" }, "memoryKind": { "type": "string", "enum": [ "system", "dedicated", "unified", "unknown" ] }, "memoryTotalBytes": { "type": "integer", "format": "int64", "minimum": 0 }, "memoryUsedBytes": { "type": "integer", "format": "int64", "minimum": 0 }, "memoryFreeBytes": { "type": "integer", "format": "int64", "minimum": 0 }, "safelyAllocatableMemoryBytes": { "type": "integer", "format": "int64", "minimum": 0, "description": "Memory Nexus may plan to use after reserving device or desktop headroom." }, "memoryConfidence": { "type": "string", "enum": [ "reported", "estimated", "partial", "unknown" ] }, "integrated": { "type": "boolean" }, "problemCodes": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "HardwareTelemetryProblem": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "deviceId": { "type": "string", "description": "Opaque public device ID when the problem applies to one detected device." } }, "additionalProperties": false }, "Capabilities": { "type": "object", "description": "Authenticated client discovery document for API-first integrations. It uses stable IDs and route names instead of display labels, and intentionally omits provider records, provider credentials, credential references, local paths, runtime roots, and generated artifact paths.", "required": [ "object", "endpointFamilies", "providerKinds", "providerActions", "serviceActions", "modelActions", "modelRegistrySources", "scopes", "presetScopes", "presetParams", "surfaces" ], "properties": { "object": { "type": "string", "const": "msty.nexus.capabilities" }, "endpointFamilies": { "type": "array", "description": "Stable endpoint family IDs and route names supported by this Nexus build.", "items": { "$ref": "#/components/schemas/EndpointFamilyCapability" } }, "providerKinds": { "type": "array", "description": "Provider/runtime kinds available to configure, without any user provider records or credentials.", "items": { "$ref": "#/components/schemas/ProviderKindCapability" } }, "providerActions": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderAction" } }, "serviceActions": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceAction" } }, "modelActions": { "type": "array", "items": { "$ref": "#/components/schemas/ModelAction" } }, "modelRegistrySources": { "type": "array", "items": { "$ref": "#/components/schemas/ModelRegistrySource" } }, "scopes": { "type": "array", "description": "Shared ownership scopes supported by scoped provider, model, preset, and token records.", "items": { "$ref": "#/components/schemas/Scope" } }, "presetParams": { "$ref": "#/components/schemas/PresetParamCapabilities" }, "presetScopes": { "type": "array", "description": "Compatibility field mirroring scopes for clients that already read preset-scope capability data.", "items": { "$ref": "#/components/schemas/Scope" } }, "surfaces": { "$ref": "#/components/schemas/CapabilitySurfaces" } }, "additionalProperties": false }, "EndpointFamilyCapability": { "type": "object", "required": [ "id", "route", "streaming", "routes" ], "properties": { "id": { "$ref": "#/components/schemas/EndpointFamily" }, "route": { "type": "string", "enum": [ "/v1/chat/completions", "/v1/embeddings", "/v1/responses", "/v1/messages", "/v1/images/generations", "/v1/audio/speech", "/v1/audio/transcriptions", "/v1/rerank" ] }, "streaming": { "type": "boolean" }, "routes": { "type": "array", "description": "Operation-level gateway route discovery for this endpoint family. Sibling accounting, compaction, and response-ID routes stay under the same model endpoint family instead of becoming separate model capabilities.", "items": { "$ref": "#/components/schemas/EndpointRouteCapability" } } }, "additionalProperties": false }, "EndpointRouteCapability": { "type": "object", "required": [ "id", "method", "path", "streaming" ], "properties": { "id": { "type": "string", "description": "Stable operation ID within the endpoint family, for example create, compact, or count_tokens." }, "method": { "type": "string", "enum": [ "GET", "POST", "DELETE" ] }, "path": { "type": "string", "enum": [ "/v1/chat/completions", "/v1/embeddings", "/v1/responses", "/v1/responses/input_tokens", "/v1/responses/compact", "/v1/responses/{id}", "/v1/responses/{id}/input_items", "/v1/responses/{id}/cancel", "/v1/messages", "/v1/messages/count_tokens", "/v1/images/generations", "/v1/images/edits", "/v1/audio/speech", "/v1/audio/transcriptions", "/v1/rerank" ] }, "streaming": { "type": "boolean" } }, "additionalProperties": false }, "ProviderKindCapability": { "type": "object", "required": [ "kind", "local", "credentialRequired", "endpointFamilies", "modelActions", "serviceActions" ], "properties": { "kind": { "$ref": "#/components/schemas/ProviderKind" }, "local": { "type": "boolean" }, "credentialRequired": { "type": "boolean" }, "endpointFamilies": { "type": "array", "items": { "$ref": "#/components/schemas/EndpointFamily" } }, "modelActions": { "type": "array", "description": "Model actions this provider/runtime kind supports. This is a per-kind support matrix, not just the global action vocabulary.", "items": { "$ref": "#/components/schemas/ModelAction" } }, "serviceActions": { "type": "array", "description": "Runtime service actions this provider/runtime kind supports. Online providers return an empty array.", "items": { "$ref": "#/components/schemas/ServiceAction" } }, "platforms": { "type": "array", "description": "Optional GOOS identifiers for platform-limited provider/runtime kinds. Empty or omitted means cross-platform.", "items": { "type": "string" } }, "accountProviders": { "type": "array", "description": "Subscription account providers a runtime kind can connect through the /v1/services/{id}/accounts routes. Empty or omitted means the kind has no account surface.", "items": { "$ref": "#/components/schemas/AccountProvider" } } }, "additionalProperties": false }, "CapabilitySurfaces": { "type": "object", "required": [ "settings", "auditEvents", "providerDiagnostics", "serviceDiagnostics", "jobEvents", "gatewayStreaming", "usageMetrics", "loadedModels", "libraryHealth" ], "properties": { "settings": { "type": "boolean" }, "auditEvents": { "type": "boolean" }, "providerDiagnostics": { "type": "boolean" }, "serviceDiagnostics": { "type": "boolean" }, "jobEvents": { "type": "boolean" }, "gatewayStreaming": { "type": "boolean" }, "usageMetrics": { "type": "boolean" }, "cluster": { "$ref": "#/components/schemas/FeatureSurface", "description": "Optional distributed MLX cluster add-on status. Omitted when the runtime has no cluster entitlement or development feature flag." }, "loadedModels": { "type": "boolean", "description": "GET /v1/loaded-models occupancy reporting is available." }, "libraryHealth": { "type": "boolean", "description": "GET /v1/model-library/health scanning is available." } }, "additionalProperties": false }, "FeatureSurface": { "type": "object", "description": "Runtime feature status for optional product surfaces. Clients should use available=false plus reason/source for disabled UI affordances instead of inferring access from SDK method presence.", "required": [ "available", "reason", "source" ], "properties": { "available": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "available", "not_entitled", "not_yet_valid", "expired", "unknown_feature" ] }, "source": { "type": "string", "enum": [ "none", "environment", "entitlement" ] }, "customerId": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "maxMembers": { "type": "integer", "minimum": 0 }, "artifactChannel": { "type": "string" } }, "additionalProperties": false }, "LoadedModel": { "type": "object", "description": "One model currently resident in a local runtime's memory.", "required": [ "serviceId", "runtimeModel", "state" ], "properties": { "serviceId": { "type": "string" }, "providerId": { "type": "string", "description": "Set when the runtime entry matches a Nexus catalog record." }, "modelId": { "type": "string", "description": "Nexus catalog model ID when matched." }, "runtimeModel": { "type": "string", "description": "Runtime-native model name." }, "state": { "type": "string", "enum": [ "loaded", "loading" ] }, "sizeBytes": { "type": "integer", "format": "int64" }, "vramBytes": { "type": "integer", "format": "int64" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Keep-alive deadline after which the runtime plans to evict the model." } } }, "LoadedModelServiceProbe": { "type": "object", "description": "Whether a runtime's occupancy API answered, so clients can distinguish nothing-loaded from could-not-ask.", "required": [ "serviceId", "status" ], "properties": { "serviceId": { "type": "string" }, "status": { "type": "string", "enum": [ "ok", "unreachable", "invalid_response" ] } } }, "LoadedModelsReport": { "type": "object", "required": [ "loadedModels", "probes" ], "properties": { "loadedModels": { "type": "array", "items": { "$ref": "#/components/schemas/LoadedModel" } }, "probes": { "type": "array", "items": { "$ref": "#/components/schemas/LoadedModelServiceProbe" } } } }, "LibraryHealthIssue": { "type": "object", "description": "One detected drift between the model catalog and managed storage or runtime state.", "required": [ "type", "serviceId", "suggestedRepair" ], "properties": { "type": { "type": "string", "enum": [ "missing_file", "size_mismatch", "orphan_file", "stray_file", "record_missing_upstream", "upstream_not_cataloged" ] }, "serviceId": { "type": "string" }, "providerId": { "type": "string" }, "modelId": { "type": "string" }, "modelName": { "type": "string" }, "path": { "type": "string", "description": "Relative to Nexus-managed storage; never an absolute local path." }, "sizeBytes": { "type": "integer", "format": "int64" }, "expectedSizeBytes": { "type": "integer", "format": "int64", "description": "Size recorded at pull/import time when it differs from disk." }, "suggestedRepair": { "type": "string", "enum": [ "sync", "pull", "delete", "none" ], "description": "Existing model action that fixes the issue; repairs never introduce new mutation paths." } } }, "LibraryHealthServiceScan": { "type": "object", "description": "Whether one service's storage and runtime state could be examined.", "required": [ "serviceId", "status" ], "properties": { "serviceId": { "type": "string" }, "status": { "type": "string", "enum": [ "ok", "skipped", "unreachable", "failed" ] } } }, "LibraryHealthReport": { "type": "object", "required": [ "healthy", "issues", "scans", "scannedModels" ], "properties": { "healthy": { "type": "boolean", "description": "True when no issues were found. Unreachable runtimes do not make a library unhealthy." }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/LibraryHealthIssue" } }, "scans": { "type": "array", "items": { "$ref": "#/components/schemas/LibraryHealthServiceScan" } }, "untrackedBytes": { "type": "integer", "format": "int64", "description": "On-disk bytes in managed storage no catalog record accounts for." }, "scannedModels": { "type": "integer" } } }, "ErrorEnvelope": { "type": "object", "required": [ "type", "error", "request_id" ], "properties": { "type": { "type": "string", "const": "error", "description": "Provider-SDK-compatible envelope discriminator." }, "error": { "$ref": "#/components/schemas/APIError" }, "request_id": { "type": [ "string", "null" ], "description": "Generated Nexus request identifier. It matches the X-Msty-Nexus-Request-Id response header when an HTTP request context is available. OpenAI-compatible X-Request-Id and Anthropic-compatible request-id response aliases are also set for SDK compatibility. The field may be null only for direct internal error writer calls outside request handling." } } }, "ResponseWarning": { "type": "object", "required": [ "code", "messageKey" ], "properties": { "code": { "type": "string", "enum": [ "MODEL_REGISTRY_SOURCE_UNAVAILABLE", "GPU_FALLBACK_TO_CPU", "GPU_PLACEMENT_VERIFICATION_LIMITED" ], "description": "Stable machine-readable warning code used by response warnings and job warningCode metadata. Response-warning clients localize by messageKey; job clients map warningCode to their own localized copy." }, "source": { "type": "string", "description": "Optional warning source identifier." }, "messageKey": { "type": "string", "description": "Localization key for client-owned warning copy." } }, "additionalProperties": false }, "APIError": { "type": "object", "required": [ "code", "message", "type", "param", "messageKey" ], "properties": { "code": { "type": "string", "enum": [ "UNAUTHORIZED", "INVALID_JSON", "INVALID_REQUEST", "CORS_ORIGIN_NOT_ALLOWED", "MISSING_MODEL", "MODEL_NOT_FOUND", "RESPONSE_NOT_FOUND", "MODEL_ENDPOINT_NOT_SUPPORTED", "PRESET_NOT_FOUND", "ROUTE_PACK_NOT_FOUND", "SERVICE_NOT_FOUND", "SERVICE_DISABLED", "SERVICE_NOT_RUNNING", "SERVICE_ACCOUNTS_UNAVAILABLE", "JOB_NOT_FOUND", "JOB_NOT_CANCELLABLE", "JOB_NOT_CLEARABLE", "RESOURCE_IN_USE", "FEATURE_NOT_ENTITLED", "CLUSTER_ALREADY_FORMED", "CLUSTER_NOT_FORMED", "CLUSTER_COORDINATOR_NOT_MEMBER", "CLUSTER_LAUNCHER_UNAVAILABLE", "CLUSTER_DISCOVERY_UNAVAILABLE", "CLUSTER_NO_MEMBERS", "CLUSTER_NOT_DISCOVERED", "CLUSTER_MESH_INCOMPLETE", "CLUSTER_FABRIC_NOT_READY", "CLUSTER_COORDINATOR_NOT_READY", "CLUSTER_MEMBERSHIP_UNAVAILABLE", "CLUSTER_MEMBER_NOT_FOUND", "CLUSTER_MEMBER_INVALID", "CLUSTER_MEMBER_LIMIT_EXCEEDED", "CLUSTER_JOIN_TOKEN_INVALID", "CLUSTER_JOIN_TOKEN_LIMIT_EXCEEDED", "TOKEN_NOT_FOUND", "PAIRING_REQUEST_NOT_ALLOWED", "PAIRING_REQUEST_NOT_FOUND", "PAIRING_REQUEST_LIMIT_EXCEEDED", "PAIRING_CALLBACK_FAILED", "MODEL_REGISTRY_REQUEST_FAILED", "PROVIDER_NOT_FOUND", "PROVIDER_NOT_CONFIGURED", "PROVIDER_REQUEST_FAILED", "CREDENTIAL_STORE_ERROR", "GAUGE_DISABLED", "GAUGE_SOURCE_NOT_FOUND", "GAUGE_SOURCE_DISABLED", "GAUGE_REFRESH_IN_PROGRESS", "GAUGE_ALERT_RULE_NOT_FOUND", "GAUGE_ALERT_EVENT_NOT_FOUND", "GAUGE_BUDGET_NOT_FOUND", "GAUGE_AUTH_SESSION_NOT_FOUND", "RUNTIME_INVENTORY_UNAVAILABLE", "SMART_ROUTE_NO_COMPATIBLE_RUNTIME", "SPECULATIVE_DECODING_UNSUPPORTED_RUNTIME", "SPECULATIVE_DECODING_INVALID_DRAFT_MODEL", "SPECULATIVE_DECODING_VALIDATION_FAILED", "MODEL_PLACEMENT_UNAVAILABLE", "MODEL_PLACEMENT_REVISION_CONFLICT", "MODEL_PLACEMENT_NOT_APPLICABLE", "MODEL_PLACEMENT_RELOAD_CONFIRMATION_REQUIRED", "MODEL_PLACEMENT_ROLLBACK_UNAVAILABLE", "MODEL_BENCHMARK_UNAVAILABLE", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "not_found_error", "rate_limit_error", "timeout_error", "api_error", "invalid_request_error" ], "description": "Provider-SDK-compatible coarse error type derived from the HTTP status." }, "param": { "type": [ "string", "null" ], "description": "Provider-SDK-compatible invalid parameter field. Nexus sets this for INVALID_REQUEST responses that include one invalid field and keeps precise context in details." }, "messageKey": { "type": "string", "description": "Stable localization key derived from error.code, for example error.model.not.found." }, "details": { "type": "object", "additionalProperties": true } }, "additionalProperties": false }, "GatewayRequest": { "type": "object", "description": "Base gateway request shape. Endpoint handlers also validate stable API-family fields: chat completions require message objects and Anthropic Messages applies provider-scoped messages/max_tokens rules. Responses requests are routed by model and provider-specific fields are passed through.", "required": [ "model" ], "properties": { "model": { "type": "string", "description": "Direct model ID such as openai/gpt-test, preset reference such as @preset/coder-fast, or Smart Route reference such as @route/research on generation routes." } }, "additionalProperties": true }, "ImageGenerationRequest": { "type": "object", "description": "OpenAI-shaped image generation request. Only model and prompt are validated by Nexus; other provider fields pass through.", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "description": "Nexus model ID, alias, or preset reference." }, "prompt": { "type": "string" }, "n": { "type": "integer" }, "size": { "type": "string" }, "quality": { "type": "string" }, "response_format": { "type": "string" }, "stream": { "type": "boolean", "description": "Providers that support it stream partial images over SSE." } }, "additionalProperties": true }, "ImageEditMultipartRequest": { "type": "object", "description": "OpenAI-shaped image edit upload. Nexus requires exactly one text model field, validates prompt and image/image[] file presence, rewrites model to the provider model ID, and forwards other non-model form fields unchanged.", "required": [ "model", "prompt", "image" ], "properties": { "model": { "type": "string", "description": "Nexus model ID or alias. Multipart routes do not accept preset or route-pack references." }, "prompt": { "type": "string" }, "image": { "oneOf": [ { "type": "string", "format": "binary" }, { "type": "array", "items": { "type": "string", "format": "binary" } } ], "description": "Image file part. Nexus also accepts OpenAI's image[] array form." }, "mask": { "type": "string", "format": "binary" }, "n": { "type": "integer" }, "size": { "type": "string" }, "quality": { "type": "string" }, "response_format": { "type": "string" } }, "additionalProperties": true }, "AudioSpeechRequest": { "type": "object", "description": "OpenAI-shaped text-to-speech request. Only model and input are validated by Nexus; voice and format fields pass through.", "required": [ "model", "input" ], "properties": { "model": { "type": "string", "description": "Nexus model ID, alias, or preset reference." }, "input": { "type": "string" }, "voice": { "type": "string" }, "response_format": { "type": "string" }, "speed": { "type": "number" } }, "additionalProperties": true }, "AudioTranscriptionMultipartRequest": { "type": "object", "description": "OpenAI-shaped audio transcription upload. Nexus requires exactly one text model field, validates file presence, rewrites model to the provider model ID, and forwards other non-model form fields unchanged.", "required": [ "model", "file" ], "properties": { "model": { "type": "string", "description": "Nexus model ID or alias. Multipart routes do not accept preset or route-pack references." }, "file": { "type": "string", "format": "binary" }, "language": { "type": "string" }, "prompt": { "type": "string" }, "response_format": { "type": "string" }, "temperature": { "type": "number" }, "stream": { "type": "boolean", "description": "Providers that support it stream transcription events over SSE." } }, "additionalProperties": true }, "AudioTranscriptionJSONRequest": { "type": "object", "description": "JSON transcription variant (OpenRouter shape) with base64 audio.", "required": [ "model", "input_audio" ], "properties": { "model": { "type": "string" }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string" } } } }, "additionalProperties": true }, "RerankRequest": { "type": "object", "description": "Vendor-neutral rerank request (Jina/Cohere shape) as served by llama.cpp and vLLM.", "required": [ "model", "query", "documents" ], "properties": { "model": { "type": "string", "description": "Nexus model ID, alias, or preset reference." }, "query": { "type": "string" }, "documents": { "type": "array", "items": { "type": "string" } }, "top_n": { "type": "integer" } }, "additionalProperties": true }, "AudioTranscriptionForm": { "type": "object", "description": "Multipart transcription form. Nexus validates only model and the file part; other fields pass through.", "required": [ "model", "file" ], "properties": { "model": { "type": "string", "description": "Nexus model ID or alias (presets are not accepted on multipart routes)." }, "file": { "type": "string", "format": "binary" }, "language": { "type": "string" }, "prompt": { "type": "string" }, "response_format": { "type": "string" }, "stream": { "type": "boolean" } } }, "ImageEditForm": { "type": "object", "description": "Multipart image-edit form. Nexus validates model, prompt, and the image part; other fields pass through.", "required": [ "model", "prompt", "image" ], "properties": { "model": { "type": "string", "description": "Nexus model ID or alias (presets are not accepted on multipart routes)." }, "prompt": { "type": "string" }, "image": { "type": "string", "format": "binary", "description": "One or more image parts; the image[] array form is also accepted." }, "mask": { "type": "string", "format": "binary" }, "n": { "type": "integer" }, "size": { "type": "string" } } }, "OpenAIChatMessage": { "type": "object", "description": "JSON-open OpenAI-compatible chat message. Nexus validates that chat messages are objects and forwards provider-specific message fields unchanged.", "properties": { "role": { "type": "string", "description": "OpenAI-compatible message role such as developer, system, user, assistant, or tool. Nexus leaves role compatibility to the selected upstream provider." }, "content": { "description": "OpenAI-compatible message content. Providers may accept strings, multimodal content-part arrays, or provider-specific values." } }, "additionalProperties": true }, "OpenAIChatCompletionsRequest": { "type": "object", "description": "OpenAI-compatible chat completions request. Nexus requires model and messages as an array of objects for routing and shape validation, rejects non-null stream_options unless stream is true, then forwards provider-specific optional fields unchanged.", "required": [ "model", "messages" ], "properties": { "model": { "type": "string", "description": "Direct model ID such as openai/gpt-test, preset reference such as @preset/coder-fast, or Smart Route reference such as @route/research." }, "messages": { "type": "array", "description": "OpenAI-style chat messages.", "items": { "$ref": "#/components/schemas/OpenAIChatMessage" } }, "stream": { "type": "boolean" }, "stream_options": { "description": "Streaming options for Chat Completions calls. Nexus accepts this only when stream is true and forwards provider-specific option fields unchanged.", "oneOf": [ { "$ref": "#/components/schemas/OpenAIChatStreamOptions" }, { "type": "null" } ] } }, "additionalProperties": true }, "OpenAIChatStreamOptions": { "type": "object", "description": "OpenAI Chat Completions streaming options. Provider-specific fields remain open for compatibility; include_usage and include_obfuscation are documented OpenAI streaming controls.", "properties": { "include_usage": { "type": "boolean" }, "include_obfuscation": { "type": "boolean" } }, "additionalProperties": true }, "OpenAIResponsePrompt": { "type": "object", "description": "OpenAI Responses prompt-template reference. Nexus forwards variables unchanged and relies on the selected upstream provider to validate prompt ownership and variable shape.", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Provider prompt template identifier." }, "version": { "type": "string", "description": "Optional provider prompt version." }, "variables": { "type": "object", "description": "Prompt variables forwarded to the upstream provider.", "additionalProperties": true } }, "additionalProperties": true }, "OpenAIResponsesRequest": { "type": "object", "description": "OpenAI Responses-compatible request. Nexus requires model for local routing, rejects non-null conversation together with non-null previous_response_id, rejects non-null stream_options unless stream is true, and leaves input, prompt, tool, and provider-specific fields open for upstream compatibility.", "required": [ "model" ], "properties": { "model": { "type": "string", "description": "Direct model ID such as openai/gpt-test, preset reference such as @preset/coder-fast, or Smart Route reference such as @route/research." }, "input": { "description": "Common Responses API input value. Nexus does not require this field because some provider-supported Responses shapes are prompt-driven or conversation-driven." }, "prompt": { "description": "Optional prompt-template reference for prompt-driven Responses calls.", "oneOf": [ { "$ref": "#/components/schemas/OpenAIResponsePrompt" }, { "type": "null" } ] }, "conversation": { "description": "Optional conversation reference or provider-specific conversation object for stateful Responses calls. A non-null value must not be sent with non-null previous_response_id.", "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] }, "previous_response_id": { "type": [ "string", "null" ], "description": "Optional previous response ID for stateful Responses calls. A non-null value must not be sent with non-null conversation." }, "stream": { "type": "boolean" }, "stream_options": { "description": "Streaming options for Responses calls. Nexus accepts this only when stream is true and forwards provider-specific option fields unchanged.", "oneOf": [ { "$ref": "#/components/schemas/OpenAIResponsesStreamOptions" }, { "type": "null" } ] } }, "additionalProperties": true }, "OpenAIResponsesInputTokensRequest": { "type": "object", "description": "OpenAI Responses input-token counting request. Nexus requires model for local routing, uses the same state fields as Responses creation, and forwards provider-specific fields unchanged. The schema intentionally omits stream and stream_options because token counting is a unary accounting call.", "required": [ "model" ], "properties": { "model": { "type": "string", "description": "Direct model ID such as openai/gpt-test or preset reference such as @preset/coder-fast. Smart Route @route references are not supported for Responses input-token counting in the first milestone." }, "input": { "description": "Input value to count according to the selected provider's Responses tokenizer." }, "prompt": { "description": "Optional prompt-template reference for prompt-driven token counting.", "oneOf": [ { "$ref": "#/components/schemas/OpenAIResponsePrompt" }, { "type": "null" } ] }, "conversation": { "description": "Optional conversation reference or provider-specific conversation object.", "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] }, "previous_response_id": { "type": [ "string", "null" ], "description": "Optional previous response ID for stateful token counting." } }, "additionalProperties": true }, "OpenAIResponsesCompactRequest": { "type": "object", "description": "OpenAI Responses compact request. Nexus requires model for local routing, forwards provider-specific fields unchanged, and intentionally omits stream and stream_options because compaction is a unary Responses-family call.", "required": [ "model" ], "properties": { "model": { "type": "string", "description": "Direct model ID such as openai/gpt-test or preset reference such as @preset/coder-fast. Smart Route @route references are not supported for Responses compact in the first milestone." }, "input": { "description": "Input value to compact according to the selected provider's Responses compaction behavior." }, "instructions": { "type": "string", "description": "Optional system or developer instructions for the compaction pass." }, "previous_response_id": { "type": [ "string", "null" ], "description": "Optional previous response ID for stateful compaction." } }, "additionalProperties": true }, "OpenAIResponsesStreamOptions": { "type": "object", "description": "OpenAI Responses streaming options. Provider-specific fields remain open for compatibility; include_obfuscation is documented by OpenAI for stream payload-size obfuscation control.", "properties": { "include_obfuscation": { "type": "boolean" } }, "additionalProperties": true }, "OpenAIEmbeddingsRequest": { "type": "object", "description": "OpenAI-compatible embeddings request. Nexus requires model and input for routing and shape validation, then forwards provider-specific optional fields unchanged.", "required": [ "model", "input" ], "properties": { "model": { "type": "string", "description": "Direct model ID such as openai/text-embedding-3-small or preset reference such as @preset/search-embed. Smart Route @route references are not supported for embeddings in the first milestone." }, "input": { "description": "String, token array, or batch input accepted by OpenAI-compatible embeddings providers." }, "encoding_format": { "type": "string" }, "dimensions": { "type": "integer", "minimum": 1 } }, "additionalProperties": true }, "AnthropicMessage": { "type": "object", "description": "JSON-open Anthropic-compatible message. Nexus requires role and content for Anthropic and local Anthropic-compatible providers, while provider-specific message fields remain open.", "required": [ "role", "content" ], "properties": { "role": { "type": "string", "description": "Anthropic message role. Nexus requires a non-empty string and leaves role compatibility to the upstream provider." }, "content": { "description": "Anthropic message content string or content block array." } }, "additionalProperties": true }, "AnthropicMessagesRequest": { "type": "object", "description": "Anthropic Messages-compatible request. Nexus requires model and applies provider-scoped messages/max_tokens validation. Anthropic and local Anthropic-compatible providers require messages as objects with role/content plus max_tokens. OpenRouter Messages models may use messages: null and may omit max_tokens, but Nexus validates max_tokens as a positive integer when present. Optional Anthropic and provider-specific fields are forwarded unchanged.", "required": [ "model", "messages" ], "properties": { "model": { "type": "string", "description": "Direct model ID such as anthropic/claude-test or preset reference such as @preset/coder-fast." }, "messages": { "type": [ "array", "null" ], "description": "Anthropic-style message objects. Anthropic and local Anthropic-compatible providers require an array; OpenRouter Messages models may send null.", "items": { "$ref": "#/components/schemas/AnthropicMessage" } }, "max_tokens": { "type": "integer", "minimum": 1, "description": "Maximum generated tokens. Required for Anthropic and local Anthropic-compatible providers; optional for OpenRouter Messages models. When present, Nexus requires a JSON integer, not a quoted string." }, "stream": { "type": "boolean" } }, "additionalProperties": true }, "AnthropicMessagesCountTokensRequest": { "type": "object", "description": "Anthropic Messages count-token request. Nexus requires model and messages so it can route by local model or preset, then forwards provider-specific token-count options unchanged. max_tokens and stream are intentionally omitted because this route estimates input tokens without generation.", "required": [ "model", "messages" ], "properties": { "model": { "type": "string", "description": "Direct model ID such as anthropic/claude-test or preset reference such as @preset/coder-fast." }, "messages": { "type": "array", "description": "Anthropic-style message objects to count.", "items": { "$ref": "#/components/schemas/AnthropicMessage" } } }, "additionalProperties": true }, "ModelList": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ModelListItem" } } } }, "ModelListItem": { "type": "object", "required": [ "id", "object", "created", "owned_by", "name", "msty_model" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "model" }, "created": { "type": "integer", "description": "Unix timestamp in seconds. Nexus returns 0 when the upstream release time is unknown." }, "owned_by": { "type": "string" }, "name": { "type": "string" }, "msty_model": { "$ref": "#/components/schemas/Model" } } }, "OpenAIModelInfo": { "type": "object", "required": [ "id", "object", "created", "owned_by", "name", "providerId", "scope", "endpointFamilies", "isLocal", "hidden", "msty_model" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "model" }, "created": { "type": "integer", "description": "Unix timestamp in seconds. Nexus returns 0 when the upstream release time is unknown." }, "owned_by": { "type": "string" }, "name": { "type": "string" }, "providerId": { "type": "string" }, "scope": { "$ref": "#/components/schemas/Scope" }, "endpointFamilies": { "type": "array", "items": { "$ref": "#/components/schemas/EndpointFamily" } }, "aliases": { "type": "array", "items": { "type": "string" } }, "isLocal": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "When true, the model is omitted from public model discovery and cannot be resolved by direct ID or alias for gateway requests." }, "metadata": { "type": "object", "additionalProperties": true }, "msty_model": { "$ref": "#/components/schemas/Model" } } }, "AnthropicModelList": { "type": "object", "required": [ "data", "first_id", "has_more", "last_id" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AnthropicModelInfo" } }, "first_id": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" }, "last_id": { "type": [ "string", "null" ] } } }, "AnthropicModelInfo": { "type": "object", "required": [ "id", "type", "display_name", "created_at", "capabilities", "max_input_tokens", "max_tokens" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "model" }, "display_name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 release timestamp. Nexus returns the Unix epoch when the upstream release time is unknown." }, "capabilities": { "type": "object", "additionalProperties": true, "description": "Anthropic-compatible capability metadata. Nexus returns an empty object when capability metadata is unknown." }, "max_input_tokens": { "type": "integer", "description": "Maximum input context window in tokens. Nexus returns 0 when the value is unknown." }, "max_tokens": { "type": "integer", "description": "Maximum output token value. Nexus returns 0 when the value is unknown." } } }, "ModelSearchList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ModelSearchResult" } }, "warnings": { "type": "array", "description": "Non-fatal registry source failures. Warnings use stable machine fields and never include raw upstream network errors.", "items": { "$ref": "#/components/schemas/ResponseWarning" } } }, "additionalProperties": false }, "ModelSearchResult": { "type": "object", "required": [ "source", "id", "name" ], "properties": { "source": { "$ref": "#/components/schemas/ModelRegistrySource" }, "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "tags": { "type": "array", "items": { "type": "string" } }, "downloads": { "type": "integer", "minimum": 0 }, "likes": { "type": "integer", "minimum": 0 }, "updatedAt": { "type": "string", "format": "date-time" }, "sizeBytes": { "type": "integer", "format": "int64", "minimum": 0 }, "metadata": { "type": "object", "description": "Allow-listed public job metadata. Worker records can store richer internal progress and troubleshooting data, but job list/get/cancel/event responses expose only stable IDs, enum values, counts, booleans, safe timestamps, failed cluster member IDs, and stable error codes/messages. Runtime commands, process IDs, base URLs, model directory paths, raw model action input, and arbitrary stored metadata are omitted.", "additionalProperties": true } } }, "ProviderList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Provider" } } } }, "PresetList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Preset" } } } }, "RoutePackList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RoutePack" } } } }, "TokenList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Token" } } } }, "ServiceList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } } } }, "JobList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } } } }, "JobClearResult": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "integer", "minimum": 0 } } }, "Provider": { "type": "object", "required": [ "id", "name", "kind", "scope", "enabled", "autoProxyModels", "credentialConfigured" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "$ref": "#/components/schemas/ProviderKind" }, "scope": { "$ref": "#/components/schemas/Scope" }, "baseUrl": { "type": "string", "format": "uri", "description": "Optional provider gateway base URL. When present it must be http or https with a host and must not contain URL credentials, a query string, or a fragment." }, "enabled": { "type": "boolean", "description": "Whether this provider participates in model discovery, provider model sync, and gateway routing. Disabled providers remain configured but their models and presets are hidden from /v1/models." }, "autoProxyModels": { "type": "boolean", "description": "When true, Nexus lists and routes models returned by this provider automatically using / IDs. Explicit catalog model records with the same ID take precedence." }, "credentialConfigured": { "type": "boolean", "description": "True when a credential-required provider has an upstream key stored in the local credential vault. The raw key and local credential-store reference are never returned." }, "metadata": { "type": "object", "description": "API-visible provider metadata. Credential-shaped keys such as apiKey, authorization, token, and secret are rejected.", "additionalProperties": true } } }, "ProviderInput": { "type": "object", "required": [ "name", "kind" ], "properties": { "id": { "type": "string", "description": "Optional body copy of the path provider ID. When present, it must match the path." }, "name": { "type": "string" }, "kind": { "$ref": "#/components/schemas/ProviderKind" }, "scope": { "$ref": "#/components/schemas/Scope" }, "baseUrl": { "type": "string", "format": "uri", "description": "Optional provider gateway base URL. When present it must be http or https with a host and must not contain URL credentials, a query string, or a fragment." }, "enabled": { "type": "boolean", "description": "Controls whether this provider participates in model discovery, provider model sync, and gateway routing. Defaults to true for new providers and preserves the existing setting when omitted on updates." }, "autoProxyModels": { "type": "boolean", "description": "Controls automatic listing and routing of provider-returned models through /v1/models. Defaults to true for new providers and preserves the existing setting when omitted on updates." }, "credential": { "type": "string", "writeOnly": true, "description": "Raw provider credential to store in the local secure credential store for credential-required provider kinds. Credential-free local runtime providers reject this value. It is accepted in requests only and is never returned." }, "clearCredential": { "type": "boolean", "description": "When true, deletes the stored provider credential reference. Cannot be combined with credential." }, "metadata": { "type": "object", "description": "API-visible provider metadata. Credential-shaped keys such as apiKey, authorization, token, and secret are rejected.", "additionalProperties": true } }, "additionalProperties": false }, "ProviderActionInput": { "type": "object", "required": [ "action" ], "properties": { "action": { "$ref": "#/components/schemas/ProviderAction" } }, "additionalProperties": false }, "ProviderCheck": { "type": "object", "description": "Side-effect-free provider diagnostic result. The object exposes credential presence and stable status only; it never includes raw provider credentials, credential references, upstream response bodies, or raw network error text.", "required": [ "providerId", "kind", "action", "status", "messageKey", "enabled", "credentialRequired", "credentialPresent" ], "properties": { "providerId": { "type": "string" }, "kind": { "$ref": "#/components/schemas/ProviderKind" }, "action": { "$ref": "#/components/schemas/ProviderAction" }, "status": { "$ref": "#/components/schemas/ProviderCheckStatus" }, "messageKey": { "type": "string", "description": "Localization-ready status key such as provider.check.ready." }, "enabled": { "type": "boolean" }, "credentialRequired": { "type": "boolean" }, "credentialPresent": { "type": "boolean" }, "endpointFamilies": { "type": "array", "items": { "$ref": "#/components/schemas/EndpointFamily" } }, "statusCode": { "type": "integer" }, "modelCount": { "type": "integer", "minimum": 0 } } }, "RuntimeDiscoveryScanResponse": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string", "enum": [ "msty.nexus.runtime_discovery" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/RuntimeDiscoveryCandidate" } } }, "additionalProperties": false }, "RuntimeDiscoveryRegisterRequest": { "type": "object", "required": [ "kind", "baseUrl" ], "properties": { "providerId": { "type": "string", "description": "Optional provider ID to use for the registered runtime. When omitted, Nexus chooses a stable external runtime ID." }, "runtime": { "type": "string", "description": "Display/runtime hint such as ollama, llamacpp, lmstudio, vllm, litellm, or mlx." }, "name": { "type": "string", "description": "Optional display name for the provider." }, "kind": { "$ref": "#/components/schemas/ProviderKind" }, "baseUrl": { "type": "string", "format": "uri", "description": "Loopback HTTP or HTTPS provider base URL to verify and register." } }, "additionalProperties": false }, "RuntimeDiscoveryRegisterResponse": { "type": "object", "required": [ "object", "registered", "provider" ], "properties": { "object": { "type": "string", "enum": [ "msty.nexus.runtime_discovery" ] }, "registered": { "type": "boolean", "description": "True when Nexus created a new provider; false when the base URL was already registered." }, "provider": { "$ref": "#/components/schemas/Provider" }, "candidate": { "$ref": "#/components/schemas/RuntimeDiscoveryCandidate" } }, "additionalProperties": false }, "RuntimeDiscoveryCandidate": { "type": "object", "required": [ "id", "runtime", "name", "kind", "baseUrl", "status", "registerable", "source", "confidence" ], "properties": { "id": { "type": "string", "description": "Stable candidate ID derived from kind and base URL." }, "runtime": { "type": "string" }, "name": { "type": "string" }, "kind": { "$ref": "#/components/schemas/ProviderKind" }, "baseUrl": { "type": "string", "format": "uri" }, "status": { "$ref": "#/components/schemas/RuntimeDiscoveryStatus" }, "registerable": { "type": "boolean" }, "alreadyRegistered": { "type": "boolean" }, "existingProviderId": { "type": "string" }, "modelCount": { "type": "integer", "minimum": 0 }, "models": { "type": "array", "description": "Preview of model IDs returned by the runtime. Long lists are truncated.", "items": { "$ref": "#/components/schemas/RuntimeDiscoveryModel" } }, "source": { "type": "string" }, "confidence": { "type": "string" }, "messageKey": { "type": "string", "description": "Localization-ready status key such as nexus.runtimeDiscovery.ready." } }, "additionalProperties": false }, "RuntimeDiscoveryModel": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": false }, "Token": { "type": "object", "required": [ "id", "name", "scope", "tokenPrefix", "createdAt" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "scope": { "$ref": "#/components/schemas/Scope" }, "tokenPrefix": { "type": "string", "description": "Short display prefix for identifying a token. This is not enough material to authenticate." }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "type": "string", "format": "date-time", "description": "Last successful authentication time for this managed token, when known." } }, "additionalProperties": false }, "TokenInput": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "scope": { "$ref": "#/components/schemas/Scope" } }, "additionalProperties": false }, "TokenUpdateInput": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } }, "additionalProperties": false }, "TokenCreateResponse": { "type": "object", "required": [ "token", "record" ], "properties": { "token": { "type": "string", "writeOnly": true, "description": "Plaintext local Nexus token. Returned only at creation time and never available from list/get endpoints." }, "record": { "$ref": "#/components/schemas/Token" } }, "additionalProperties": false }, "AuditEventList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEvent" } } }, "additionalProperties": false }, "AuditEvent": { "type": "object", "description": "Redacted security and lifecycle audit event. Metadata is server allow-listed and must not contain provider credentials, local Nexus tokens, request bodies, local paths, or generated artifact paths.", "required": [ "id", "action", "resourceType", "actorType", "createdAt" ], "properties": { "id": { "type": "string" }, "action": { "$ref": "#/components/schemas/AuditAction" }, "resourceType": { "$ref": "#/components/schemas/AuditResourceType" }, "resourceId": { "type": "string" }, "actorType": { "$ref": "#/components/schemas/AuditActorType" }, "actorId": { "type": "string" }, "requestId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "metadata": { "type": "object", "description": "Allow-listed scalar metadata for the audited action. Arbitrary stored keys, credentials, paths, and request bodies are omitted.", "additionalProperties": true } }, "additionalProperties": false }, "PlacementWeightPolicy": { "type": "object", "required": ["mode"], "properties": { "mode": { "type": "string", "enum": ["automatic", "maximum", "ratio", "layers"] }, "ratio": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 }, "layers": { "type": "integer", "minimum": 1 } }, "additionalProperties": false }, "PlacementDeviceSplit": { "type": "object", "required": ["deviceId", "ratio"], "properties": { "deviceId": { "type": "string", "pattern": "^gpu-[a-z0-9][a-z0-9-]{0,79}$" }, "ratio": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 } }, "additionalProperties": false }, "PlacementMultiGPU": { "type": "object", "required": ["strategy"], "properties": { "strategy": { "type": "string", "enum": ["automatic", "single", "layer", "row", "tensor"] }, "primaryDevice": { "type": "string", "pattern": "^gpu-[a-z0-9][a-z0-9-]{0,79}$" }, "splits": { "type": "array", "maxItems": 64, "items": { "$ref": "#/components/schemas/PlacementDeviceSplit" } } }, "additionalProperties": false }, "PlacementKVCache": { "type": "object", "required": ["device", "keyPrecision", "valuePrecision"], "properties": { "device": { "type": "string", "enum": ["automatic", "gpu", "cpu"] }, "keyPrecision": { "type": "string", "enum": ["automatic", "f16", "q8_0", "q4_0"] }, "valuePrecision": { "type": "string", "enum": ["automatic", "f16", "q8_0", "q4_0"] } }, "additionalProperties": false }, "ModelPlacementProfileInput": { "type": "object", "required": ["goal", "fallback", "deviceMode", "weights", "multiGpu", "kvCache", "flashAttention", "memoryMap", "memoryLock", "expectedRevision"], "properties": { "goal": { "type": "string", "enum": ["balanced", "max_speed", "max_context", "cpu_only", "custom"] }, "fallback": { "type": "string", "enum": ["allow_cpu", "require_gpu"] }, "deviceMode": { "type": "string", "enum": ["automatic", "manual"] }, "deviceIds": { "type": "array", "maxItems": 64, "uniqueItems": true, "items": { "type": "string", "pattern": "^gpu-[a-z0-9][a-z0-9-]{0,79}$" } }, "weights": { "$ref": "#/components/schemas/PlacementWeightPolicy" }, "multiGpu": { "$ref": "#/components/schemas/PlacementMultiGPU" }, "kvCache": { "$ref": "#/components/schemas/PlacementKVCache" }, "flashAttention": { "type": "string", "enum": ["automatic", "enabled", "disabled"] }, "contextLength": { "type": "integer", "minimum": 0, "maximum": 1048576 }, "batchSize": { "type": "integer", "minimum": 0, "maximum": 65536 }, "microBatchSize": { "type": "integer", "minimum": 0, "maximum": 65536 }, "cpuMoeLayers": { "type": "integer", "minimum": 0, "maximum": 10000 }, "memoryMap": { "type": "string", "enum": ["automatic", "enabled", "disabled"] }, "memoryLock": { "type": "string", "enum": ["automatic", "enabled", "disabled"] }, "expectedRevision": { "type": "integer", "format": "int64", "minimum": 1 } }, "additionalProperties": false }, "ModelPlacementProfile": { "type": "object", "required": ["object", "modelId", "goal", "fallback", "deviceMode", "weights", "multiGpu", "kvCache", "flashAttention", "memoryMap", "memoryLock", "revision"], "properties": { "object": { "type": "string", "const": "msty.nexus.model_placement_profile" }, "modelId": { "type": "string" }, "goal": { "type": "string", "enum": ["balanced", "max_speed", "max_context", "cpu_only", "custom"] }, "fallback": { "type": "string", "enum": ["allow_cpu", "require_gpu"] }, "deviceMode": { "type": "string", "enum": ["automatic", "manual"] }, "deviceIds": { "type": "array", "items": { "type": "string" } }, "weights": { "$ref": "#/components/schemas/PlacementWeightPolicy" }, "multiGpu": { "$ref": "#/components/schemas/PlacementMultiGPU" }, "kvCache": { "$ref": "#/components/schemas/PlacementKVCache" }, "flashAttention": { "type": "string", "enum": ["automatic", "enabled", "disabled"] }, "contextLength": { "type": "integer", "minimum": 0 }, "batchSize": { "type": "integer", "minimum": 0 }, "microBatchSize": { "type": "integer", "minimum": 0 }, "cpuMoeLayers": { "type": "integer", "minimum": 0 }, "memoryMap": { "type": "string", "enum": ["automatic", "enabled", "disabled"] }, "memoryLock": { "type": "string", "enum": ["automatic", "enabled", "disabled"] }, "revision": { "type": "integer", "format": "int64", "minimum": 1 }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "ModelPlacementPlanInput": { "type": "object", "properties": { "profile": { "$ref": "#/components/schemas/ModelPlacementProfileInput" } }, "additionalProperties": false }, "ModelPlacementApplyInput": { "type": "object", "required": ["profileRevision"], "properties": { "profileRevision": { "type": "integer", "format": "int64", "minimum": 1 }, "confirmReload": { "type": "boolean" } }, "additionalProperties": false }, "ModelPlacementRollbackInput": { "type": "object", "properties": { "confirmReload": { "type": "boolean", "default": false } }, "additionalProperties": false }, "PlacementDevicePlan": { "type": "object", "required": ["deviceId", "backend", "weightBytes", "totalBytes", "capacityBytes"], "properties": { "deviceId": { "type": "string" }, "backend": { "type": "string", "enum": ["metal", "cuda", "rocm", "sycl", "vulkan"] }, "weightBytes": { "type": "integer", "format": "int64", "minimum": 0 }, "weightLayers": { "type": "integer", "minimum": 0 }, "kvBytes": { "type": "integer", "format": "int64", "minimum": 0 }, "projectorBytes": { "type": "integer", "format": "int64", "minimum": 0, "description": "Memory reserved for an attached multimodal projector on this device." }, "draftWeightBytes": { "type": "integer", "format": "int64", "minimum": 0, "description": "Speculative draft-model weights reserved on this device." }, "draftWeightLayers": { "type": "integer", "minimum": 0 }, "draftKvBytes": { "type": "integer", "format": "int64", "minimum": 0, "description": "Speculative draft-model KV cache reserved on this device." }, "overheadBytes": { "type": "integer", "format": "int64", "minimum": 0 }, "totalBytes": { "type": "integer", "format": "int64", "minimum": 0 }, "capacityBytes": { "type": "integer", "format": "int64", "minimum": 0 } }, "additionalProperties": false }, "PlacementPlanMemory": { "type": "object", "required": ["weightBytes", "kvBytes", "overheadBytes", "gpuBytes", "systemBytes", "totalBytes"], "properties": { "weightBytes": { "type": "integer", "format": "int64", "minimum": 0 }, "kvBytes": { "type": "integer", "format": "int64", "minimum": 0 }, "projectorBytes": { "type": "integer", "format": "int64", "minimum": 0 }, "draftWeightBytes": { "type": "integer", "format": "int64", "minimum": 0 }, "draftKvBytes": { "type": "integer", "format": "int64", "minimum": 0 }, "overheadBytes": { "type": "integer", "format": "int64", "minimum": 0 }, "gpuBytes": { "type": "integer", "format": "int64", "minimum": 0 }, "systemBytes": { "type": "integer", "format": "int64", "minimum": 0 }, "totalBytes": { "type": "integer", "format": "int64", "minimum": 0 } }, "additionalProperties": false }, "PlacementPlanSignal": { "type": "object", "required": ["code"], "properties": { "code": { "type": "string" }, "field": { "type": "string" }, "deviceId": { "type": "string" } }, "additionalProperties": false }, "PlacementPlanApproval": { "type": "object", "required": ["code", "field", "mayAffectQuality"], "properties": { "code": { "type": "string" }, "field": { "type": "string" }, "suggestedContextLength": { "type": "integer", "minimum": 1 }, "suggestedPrecision": { "type": "string", "enum": ["f16", "q8_0", "q4_0"] }, "mayAffectQuality": { "type": "boolean" } }, "additionalProperties": false }, "PlacementRuntimeCapabilities": { "type": "object", "required": ["runtimeId", "backend", "supportsCpuPlacement", "supportsPartialWeights", "supportsManualDevices", "supportsMultiGpu", "supportsCustomSplits", "supportsRowSplit", "supportsTensorSplit", "supportsGpuKv", "supportsCpuKv", "supportsKvQuantization", "supportsFlashAttention", "usesAutomaticFlashAttention", "supportsBatchSize", "supportsMicroBatchSize", "supportsMmap", "supportsMlock", "supportsCpuMoe"], "properties": { "runtimeId": { "type": "string" }, "backend": { "type": "string" }, "supportsCpuPlacement": { "type": "boolean" }, "supportsPartialWeights": { "type": "boolean" }, "supportsManualDevices": { "type": "boolean" }, "supportsMultiGpu": { "type": "boolean" }, "supportsCustomSplits": { "type": "boolean" }, "supportsRowSplit": { "type": "boolean" }, "supportsTensorSplit": { "type": "boolean" }, "supportsGpuKv": { "type": "boolean" }, "supportsCpuKv": { "type": "boolean" }, "supportsKvQuantization": { "type": "boolean" }, "supportsFlashAttention": { "type": "boolean" }, "usesAutomaticFlashAttention": { "type": "boolean" }, "supportsBatchSize": { "type": "boolean" }, "supportsMicroBatchSize": { "type": "boolean" }, "supportsMmap": { "type": "boolean" }, "supportsMlock": { "type": "boolean" }, "supportsCpuMoe": { "type": "boolean" } }, "additionalProperties": false }, "ModelPlacementPlan": { "type": "object", "required": ["object", "modelId", "profileRevision", "goal", "fallback", "runtimeId", "backend", "capabilities", "memory", "kvDevice", "kvKeyPrecision", "kvValuePrecision", "decisions", "warnings", "requiredApprovals", "canApply"], "properties": { "object": { "type": "string", "const": "msty.nexus.model_placement_plan" }, "modelId": { "type": "string" }, "profileRevision": { "type": "integer", "format": "int64" }, "goal": { "type": "string" }, "fallback": { "type": "string" }, "runtimeId": { "type": "string" }, "backend": { "type": "string" }, "capabilities": { "$ref": "#/components/schemas/PlacementRuntimeCapabilities" }, "primaryDevice": { "type": "string" }, "devices": { "type": "array", "items": { "$ref": "#/components/schemas/PlacementDevicePlan" } }, "memory": { "$ref": "#/components/schemas/PlacementPlanMemory" }, "kvDevice": { "type": "string", "enum": ["gpu", "cpu"] }, "kvKeyPrecision": { "type": "string", "enum": ["f16", "q8_0", "q4_0"] }, "kvValuePrecision": { "type": "string", "enum": ["f16", "q8_0", "q4_0"] }, "contextLength": { "type": "integer", "minimum": 0 }, "parallelRequests": { "type": "integer", "minimum": 1, "maximum": 16, "description": "Number of simultaneous requests included in the KV-memory budget. Context length is preserved per request." }, "draftModelId": { "type": "string", "description": "Enabled draft model used as the conservative speculative-decoding memory budget." }, "decisions": { "type": "array", "items": { "$ref": "#/components/schemas/PlacementPlanSignal" } }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/PlacementPlanSignal" } }, "requiredApprovals": { "type": "array", "items": { "$ref": "#/components/schemas/PlacementPlanApproval" } }, "canApply": { "type": "boolean" } }, "additionalProperties": false }, "ModelEffectivePlacement": { "type": "object", "required": ["object", "modelId", "profileRevision", "runtimeId", "backend", "confidence", "deviceIds", "problemCodes", "verifiedAt"], "properties": { "object": { "type": "string", "const": "msty.nexus.model_effective_placement" }, "modelId": { "type": "string" }, "profileRevision": { "type": "integer", "format": "int64" }, "runtimeId": { "type": "string" }, "backend": { "type": "string" }, "confidence": { "type": "string", "enum": ["verified", "partial", "unverified", "mismatch"] }, "deviceIds": { "type": "array", "items": { "type": "string" } }, "gpuWeightBytes": { "type": "integer", "format": "int64", "minimum": 0 }, "systemWeightBytes": { "type": "integer", "format": "int64", "minimum": 0 }, "kvDevice": { "type": "string", "enum": ["gpu", "cpu"] }, "contextLength": { "type": "integer", "minimum": 0 }, "problemCodes": { "type": "array", "items": { "type": "string" } }, "verifiedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "ModelPlacementState": { "type": "object", "required": ["object", "modelId", "status", "updatedAt"], "properties": { "object": { "type": "string", "const": "msty.nexus.model_placement_state" }, "modelId": { "type": "string" }, "status": { "type": "string", "enum": ["unconfigured", "applying", "active", "degraded", "failed", "rolling_back", "rollback_failed"] }, "requestedProfile": { "$ref": "#/components/schemas/ModelPlacementProfile" }, "requestedPlan": { "$ref": "#/components/schemas/ModelPlacementPlan" }, "activeProfile": { "$ref": "#/components/schemas/ModelPlacementProfile" }, "activePlan": { "$ref": "#/components/schemas/ModelPlacementPlan" }, "effective": { "$ref": "#/components/schemas/ModelEffectivePlacement" }, "lastGoodProfile": { "$ref": "#/components/schemas/ModelPlacementProfile" }, "lastGoodPlan": { "$ref": "#/components/schemas/ModelPlacementPlan" }, "lastGoodEffective": { "$ref": "#/components/schemas/ModelEffectivePlacement" }, "failureCode": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false }, "BenchmarkSample": { "type": "object", "required": ["sequence", "promptTokens", "generatedTokens", "promptTokensPerSecond", "generationTokensPerSecond", "durationMilliseconds"], "properties": { "sequence": { "type": "integer", "minimum": 1 }, "promptTokens": { "type": "integer", "minimum": 0 }, "generatedTokens": { "type": "integer", "minimum": 0 }, "cachedPromptTokens": { "type": "integer", "minimum": 0 }, "promptTokensPerSecond": { "type": "number", "exclusiveMinimum": 0 }, "generationTokensPerSecond": { "type": "number", "exclusiveMinimum": 0 }, "durationMilliseconds": { "type": "integer", "format": "int64", "minimum": 1 } }, "additionalProperties": false }, "BenchmarkDeviceMemory": { "type": "object", "required": ["deviceId", "observedPeakBytes"], "properties": { "deviceId": { "type": "string" }, "observedPeakBytes": { "type": "integer", "format": "int64", "minimum": 0 } }, "additionalProperties": false }, "ModelBenchmark": { "type": "object", "required": ["object", "id", "modelId", "mode", "status", "protocolVersion", "runtimeId", "backend", "modelFingerprint", "hardwareFingerprint", "planFingerprint", "comparisonKey", "profileRevision", "samples", "throttleCodes", "startedAt", "finishedAt"], "properties": { "object": { "type": "string", "const": "msty.nexus.model_benchmark" }, "id": { "type": "string" }, "jobId": { "type": "string" }, "modelId": { "type": "string" }, "mode": { "type": "string", "enum": ["quick", "expert"] }, "candidate": { "type": "string", "enum": ["current", "automatic", "maximum_gpu", "single_gpu", "multi_gpu"] }, "candidateIndex": { "type": "integer", "minimum": 1 }, "candidateCount": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": ["succeeded", "failed"] }, "protocolVersion": { "type": "integer", "minimum": 1 }, "runtimeId": { "type": "string" }, "runtimeVersion": { "type": "string" }, "backend": { "type": "string" }, "modelFingerprint": { "type": "string" }, "hardwareFingerprint": { "type": "string" }, "planFingerprint": { "type": "string" }, "comparisonKey": { "type": "string" }, "profileRevision": { "type": "integer", "format": "int64" }, "profile": { "$ref": "#/components/schemas/ModelPlacementProfile" }, "plan": { "$ref": "#/components/schemas/ModelPlacementPlan" }, "effective": { "$ref": "#/components/schemas/ModelEffectivePlacement" }, "firstLoadMilliseconds": { "type": "integer", "format": "int64", "minimum": 0 }, "reloadMilliseconds": { "type": "integer", "format": "int64", "minimum": 0 }, "promptTokensPerSecond": { "type": "number", "minimum": 0 }, "generationTokensPerSecond": { "type": "number", "minimum": 0 }, "samples": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkSample" } }, "deviceMemory": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkDeviceMemory" } }, "systemMemoryObservedPeakBytes": { "type": "integer", "format": "int64", "minimum": 0 }, "throttleCodes": { "type": "array", "items": { "type": "string" } }, "failureCode": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time" }, "finishedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "ModelBenchmarkInput": { "type": "object", "properties": { "mode": { "type": "string", "enum": ["quick", "expert"], "default": "quick" } }, "additionalProperties": false }, "ModelBenchmarkList": { "type": "object", "required": ["object", "data", "hasMore"], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ModelBenchmark" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string" } }, "additionalProperties": false }, "ModelBenchmarkRecommendation": { "type": "object", "required": ["object", "modelId", "benchmarkId", "comparisonKey", "stale", "staleReasonCodes", "createdAt"], "properties": { "object": { "type": "string", "const": "msty.nexus.model_benchmark_recommendation" }, "modelId": { "type": "string" }, "benchmarkId": { "type": "string" }, "comparisonKey": { "type": "string" }, "candidate": { "type": "string", "enum": ["current", "automatic", "maximum_gpu", "single_gpu", "multi_gpu"] }, "profile": { "$ref": "#/components/schemas/ModelPlacementProfile" }, "promptSpeedup": { "type": "number", "minimum": 0 }, "generationSpeedup": { "type": "number", "minimum": 0 }, "stale": { "type": "boolean" }, "staleReasonCodes": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "Model": { "type": "object", "required": [ "id", "providerId", "name", "scope", "endpointFamilies", "isLocal", "hidden" ], "properties": { "id": { "type": "string" }, "providerId": { "type": "string" }, "name": { "type": "string" }, "scope": { "$ref": "#/components/schemas/Scope", "description": "Ownership scope for local, account, and future team catalog records." }, "endpointFamilies": { "type": "array", "items": { "$ref": "#/components/schemas/EndpointFamily" } }, "aliases": { "type": "array", "description": "Optional gateway model aliases. Aliases must be unique, path-safe, and cannot shadow another model ID.", "items": { "type": "string" } }, "isLocal": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "When true, the model is omitted from public model discovery and cannot be resolved by direct ID or alias for gateway requests." }, "metadata": { "type": "object", "description": "API-visible model metadata. Credential-shaped keys such as apiKey, authorization, token, and secret are rejected.", "additionalProperties": true } } }, "ModelInput": { "type": "object", "required": [ "providerId", "name", "endpointFamilies" ], "properties": { "id": { "type": "string", "description": "Optional body copy of the path model ID. When present, it must match the path." }, "providerId": { "type": "string" }, "name": { "type": "string" }, "scope": { "$ref": "#/components/schemas/Scope", "description": "Optional ownership scope. Defaults to local when omitted." }, "endpointFamilies": { "type": "array", "description": "Gateway endpoint families this model advertises. Every value must be supported by the referenced provider kind.", "items": { "$ref": "#/components/schemas/EndpointFamily" }, "minItems": 1 }, "aliases": { "type": "array", "description": "Optional gateway model aliases. Aliases must be unique, path-safe, and cannot shadow another model ID.", "items": { "type": "string" } }, "isLocal": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "When true, the model is omitted from /v1/models and cannot be resolved by direct ID or alias for gateway requests." }, "metadata": { "type": "object", "description": "API-visible model metadata. Credential-shaped keys such as apiKey, authorization, token, and secret are rejected.", "additionalProperties": true } }, "additionalProperties": false }, "ModelInstallCandidateList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ModelInstallCandidate" } }, "hasMore": { "type": "boolean", "description": "True when another install-candidate page is available for the same query." }, "warnings": { "type": "array", "description": "Non-fatal registry source failures. Warnings use stable machine fields and never include raw upstream network errors.", "items": { "$ref": "#/components/schemas/ResponseWarning" } } }, "additionalProperties": false }, "ModelInstallCandidate": { "type": "object", "required": [ "id", "name", "source", "serviceId", "serviceName", "serviceKind" ], "properties": { "id": { "type": "string", "description": "Opaque candidate ID stable within the search response." }, "name": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "tags": { "type": "array", "items": { "type": "string" } }, "downloads": { "type": "integer", "format": "int64" }, "likes": { "type": "integer", "format": "int64" }, "updatedAt": { "type": "string", "format": "date-time" }, "source": { "$ref": "#/components/schemas/ModelRegistrySource" }, "serviceId": { "type": "string" }, "serviceName": { "type": "string" }, "serviceKind": { "$ref": "#/components/schemas/ProviderKind" }, "model": { "type": "string" }, "modelId": { "type": "string" }, "modelSource": { "$ref": "#/components/schemas/ModelActionSource" }, "repository": { "type": "string" }, "file": { "type": "string" }, "quantization": { "type": "string", "description": "Detected quantization or precision label for GGUF candidates, such as Q4_K_M, IQ4_XS, or BF16." }, "recommended": { "type": "boolean", "description": "True when Nexus recommends this candidate among available variants for the same repository." }, "revision": { "type": "string" }, "requiresFileSelection": { "type": "boolean", "description": "True when the candidate needs a user-selected GGUF file before it can be installed." }, "installUnavailableReason": { "type": "string", "enum": [ "NO_GGUF_FILES" ], "description": "Machine-readable reason the candidate is visible but cannot be installed." }, "sizeBytes": { "type": "integer", "format": "int64", "minimum": 0 }, "installAction": { "$ref": "#/components/schemas/ModelInstallAction" } }, "additionalProperties": false }, "ModelInstallAction": { "type": "object", "required": [ "action", "serviceId", "model" ], "properties": { "action": { "$ref": "#/components/schemas/ModelAction" }, "serviceId": { "type": "string" }, "model": { "type": "string" }, "modelId": { "type": "string" }, "source": { "$ref": "#/components/schemas/ModelActionSource" }, "repository": { "type": "string" }, "file": { "type": "string" }, "revision": { "type": "string" } }, "additionalProperties": false }, "ModelActionRequest": { "type": "object", "required": [ "action" ], "description": "For pull/import/delete/load/unload, serviceId and model are required. For sync, provide exactly one of serviceId or providerId and omit model/modelId. llama.cpp pull/import/sync/delete uses the configured Nexus llama.cpp models subdirectory; pull downloads a Hugging Face GGUF and import copies a local GGUF. Either can optionally attach one multimodal projector; Nexus stores the pair as one catalog model and never exposes the projector as a chat model. sourcePath is write-only input for both model and projector. llama.cpp sync scans managed GGUF pairs, and delete removes only Nexus-managed relative model and projector files. llama.cpp load/unload requires an installed, reachable runtime and sends the relative GGUF name to the native router's POST /models/load or POST /models/unload endpoint. MLX pull downloads a Hugging Face repository snapshot into the server-configured Nexus model cache and can run before the MLX runtime is installed; sync uses the service baseUrl or the catalog default port on macOS and merges Nexus-owned cache manifests, and delete removes only Nexus-managed MLX cache records. MLX sync and delete require a recorded Nexus-managed runtime install. Cluster sync uses the private rank-0 route stored by cluster Form, retries transient startup failures from /v1/models, and registers routable cluster/ records without exposing that route publicly.", "properties": { "action": { "$ref": "#/components/schemas/ModelAction" }, "serviceId": { "type": "string", "description": "Runtime service ID, for example ollama, llamacpp, or mlx. Used for local runtime pull/import/delete/load/unload/sync where the selected runtime supports that action." }, "providerId": { "type": "string", "description": "Online provider ID, for example openai. Used for provider model sync." }, "model": { "type": "string", "description": "Runtime-native model name, for example gemma3:latest or a relative llama.cpp GGUF name. Required for pull/import/delete/load/unload and omitted for sync." }, "modelId": { "type": "string", "description": "Optional Nexus model ID associated with pull, import, delete, load, or unload. Defaults to serviceId/model." }, "source": { "$ref": "#/components/schemas/ModelActionSource" }, "sourcePath": { "type": "string", "description": "Write-only absolute local GGUF path for llama.cpp import. Nexus never returns this value in job responses, logs, or public metadata." }, "repository": { "type": "string", "description": "Hugging Face repository for llama.cpp pull, for example Qwen/Qwen3-4B-GGUF." }, "file": { "type": "string", "description": "Hugging Face GGUF file path inside repository for llama.cpp pull." }, "revision": { "type": "string", "description": "Hugging Face revision for llama.cpp pull. Defaults to main." }, "projector": { "$ref": "#/components/schemas/ModelActionFileSource" } }, "additionalProperties": false }, "ModelAction": { "type": "string", "enum": [ "pull", "import", "delete", "load", "unload", "sync" ] }, "ModelActionSource": { "type": "string", "enum": [ "local_file", "huggingface" ], "description": "Source selector for file-backed model actions. llama.cpp pull accepts huggingface; llama.cpp import accepts local_file." }, "ModelActionFileSource": { "type": "object", "required": [ "source" ], "description": "Optional multimodal projector source for a llama.cpp model action. A local sourcePath is write-only and never appears in jobs, catalog metadata, logs, or generated runtime presets. Hugging Face repository and revision may match the model; file identifies the projector GGUF.", "properties": { "source": { "$ref": "#/components/schemas/ModelActionSource" }, "sourcePath": { "type": "string", "description": "Write-only absolute local GGUF path for a projector imported on the Runtime machine." }, "repository": { "type": "string" }, "file": { "type": "string" }, "revision": { "type": "string" } }, "additionalProperties": false }, "AccelerationMode": { "type": "string", "enum": [ "off", "classic_draft", "omlx_dflash", "omlx_native_mtp" ], "description": "Preset acceleration mode. classic_draft maps to llama.cpp draft-helper acceleration with a validated helper model. omlx_dflash maps to Nexus-managed MLX helper acceleration with a validated helper model. omlx_native_mtp maps to Nexus-managed MLX native MTP acceleration and does not require a helper model. Direct target model calls remain unaccelerated." }, "AccelerationCompatibilityStatus": { "type": "string", "enum": [ "unknown", "valid", "invalid", "stale" ] }, "AccelerationReloadRequirement": { "type": "string", "enum": [ "none", "next_load", "restart_runtime" ], "description": "When the saved profile takes effect for the owning local runtime." }, "Preset": { "type": "object", "required": [ "id", "slug", "name", "scope", "modelId", "routing" ], "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "scope": { "$ref": "#/components/schemas/Scope" }, "modelId": { "type": "string" }, "params": { "type": "object", "description": "Reusable request parameter defaults. The top-level model field is reserved and credential-shaped keys such as apiKey, authorization, token, and secret are rejected.", "additionalProperties": true }, "providerOptions": { "type": "object", "description": "Reusable provider-specific request defaults, keyed by provider kind with \"*\" applying to every provider. Only the wildcard bucket and the bucket matching the resolved provider are sent upstream. A legacy flat map is accepted and normalized into the wildcard bucket on write. Applied after params and before explicit request fields. The top-level model field is reserved and credential-shaped keys such as apiKey, authorization, token, and secret are rejected.", "additionalProperties": true }, "thinking": { "$ref": "#/components/schemas/PresetThinking" }, "promptCache": { "$ref": "#/components/schemas/PresetPromptCache" }, "routing": { "$ref": "#/components/schemas/RoutingPolicy" }, "acceleration": { "$ref": "#/components/schemas/PresetAccelerationProfile", "description": "Optional preset-owned acceleration state. When enabled, Nexus routes this preset through a generated local runtime alias; direct target model calls remain unaccelerated." }, "warnings": { "type": "array", "description": "Settings the preset's current target model cannot honor. Computed on read against the live catalog and never persisted, so a preset that becomes unsupported after a model change reports it on the next read.", "items": { "$ref": "#/components/schemas/PresetWarning" } } } }, "PresetInput": { "type": "object", "required": [ "name", "modelId" ], "properties": { "id": { "type": "string", "description": "Optional stable internal ID. When omitted, the slug is used for new presets and the existing ID is preserved for updates." }, "slug": { "type": "string", "description": "Optional body copy of the path slug. When present, it must match the path." }, "name": { "type": "string" }, "scope": { "$ref": "#/components/schemas/Scope" }, "modelId": { "type": "string" }, "params": { "type": "object", "description": "Reusable request parameter defaults. The top-level model field is reserved and credential-shaped keys such as apiKey, authorization, token, and secret are rejected.", "additionalProperties": true }, "providerOptions": { "type": "object", "description": "Reusable provider-specific request defaults, keyed by provider kind with \"*\" applying to every provider. Only the wildcard bucket and the bucket matching the resolved provider are sent upstream. A legacy flat map is accepted and normalized into the wildcard bucket on write. Applied after params and before explicit request fields. The top-level model field is reserved and credential-shaped keys such as apiKey, authorization, token, and secret are rejected.", "additionalProperties": true }, "thinking": { "$ref": "#/components/schemas/PresetThinking" }, "promptCache": { "$ref": "#/components/schemas/PresetPromptCache" }, "routing": { "allOf": [ { "$ref": "#/components/schemas/RoutingPolicy" } ], "description": "Routing shape is schema-ready. The initial API accepts preferLocal and rejects fallback flags when true." }, "acceleration": { "$ref": "#/components/schemas/PresetAccelerationInput", "description": "Optional speed-up settings for this preset. Omit to preserve the existing preset acceleration state; send enabled:false to turn it off." } }, "additionalProperties": false }, "ThinkingEffort": { "type": "string", "enum": [ "off", "minimal", "low", "medium", "high", "max" ], "description": "Vendor-neutral reasoning level. Nexus translates it to each provider's wire contract at request time. \"off\" actively disables reasoning and \"max\" means the highest effort the resolved provider exposes. Omitting the thinking object entirely leaves the request untouched, which is different from \"off\"." }, "ThinkingDisplay": { "type": "string", "enum": [ "summarized", "omitted" ], "description": "Whether reasoning content reaches the caller. Sent as a provider field where one exists; otherwise Nexus filters the relayed response." }, "PromptCacheTTL": { "type": "string", "enum": [ "5m", "1h" ], "description": "Cache breakpoint lifetime. Omit to use the provider default. 1h adds the provider's extended-cache beta opt-in." }, "PresetThinking": { "type": "object", "description": "Vendor-neutral reasoning defaults for this preset. Omit the object to take no position on reasoning.", "properties": { "effort": { "$ref": "#/components/schemas/ThinkingEffort" }, "display": { "$ref": "#/components/schemas/ThinkingDisplay" } }, "additionalProperties": false }, "PresetPromptCache": { "type": "object", "required": [ "enabled" ], "description": "Provider prompt-cache breakpoints for this preset. Honored by Anthropic models; other provider kinds report an unsupported_prompt_cache warning instead of silently doing nothing.", "properties": { "enabled": { "type": "boolean" }, "ttl": { "$ref": "#/components/schemas/PromptCacheTTL" } }, "additionalProperties": false }, "PresetWarning": { "type": "object", "required": [ "code", "messageKey" ], "description": "A preset setting the resolved provider cannot honor. Codes are stable and machine-readable; messageKey is for client localization.", "properties": { "code": { "type": "string", "enum": [ "unsupported_param", "unsupported_thinking", "unsupported_thinking_display", "unsupported_prompt_cache", "unknown_provider_bucket" ] }, "messageKey": { "type": "string" }, "field": { "type": "string" } } }, "PresetValidationResult": { "type": "object", "required": [ "valid" ], "properties": { "valid": { "type": "boolean" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/PresetWarning" } } } }, "PresetParamCapabilities": { "type": "object", "required": [ "thinkingEfforts", "thinkingDisplays", "promptCacheTtls", "providerOptionBuckets", "thinkingProviderKinds", "thinkingEffortProviderKinds", "promptCacheProviderKinds" ], "description": "Preset generation vocabulary this build accepts. Effort order runs from least to most reasoning so clients can render it as a scale without re-sorting.", "properties": { "thinkingEfforts": { "type": "array", "items": { "$ref": "#/components/schemas/ThinkingEffort" } }, "thinkingDisplays": { "type": "array", "items": { "$ref": "#/components/schemas/ThinkingDisplay" } }, "promptCacheTtls": { "type": "array", "items": { "$ref": "#/components/schemas/PromptCacheTTL" } }, "providerOptionBuckets": { "type": "array", "description": "Keys a namespaced providerOptions map may use. \"*\" applies to every provider.", "items": { "type": "string" } }, "thinkingProviderKinds": { "type": "array", "description": "Provider kinds that can control reasoning at all.", "items": { "$ref": "#/components/schemas/ProviderKind" } }, "thinkingEffortProviderKinds": { "type": "array", "description": "Provider kinds that accept a graded thinking effort rather than only an on/off toggle.", "items": { "$ref": "#/components/schemas/ProviderKind" } }, "promptCacheProviderKinds": { "type": "array", "description": "Provider kinds where preset prompt caching inserts real cache breakpoints.", "items": { "$ref": "#/components/schemas/ProviderKind" } } } }, "RoutePack": { "type": "object", "required": [ "id", "slug", "name", "scope", "enabled", "fallbackModelId" ], "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "scope": { "$ref": "#/components/schemas/Scope" }, "enabled": { "type": "boolean", "description": "Disabled route packs remain stored but are not exposed as @route/{slug} synthetic models." }, "fallbackModelId": { "type": "string", "description": "Generation-capable model used when classification is unavailable, invalid, slow, or selects an unavailable target." }, "routes": { "type": "array", "items": { "$ref": "#/components/schemas/RoutePackRoute" } }, "metadata": { "$ref": "#/components/schemas/RoutePackMetadata" } } }, "RoutePackMetadata": { "type": "object", "description": "API-visible route-pack metadata. Only owner, source, version, and tags are accepted. String values must be bounded and must not be local paths; credential-shaped, prompt, path, and router-internal fields are rejected.", "properties": { "owner": { "type": "string", "minLength": 1, "maxLength": 256 }, "source": { "type": "string", "minLength": 1, "maxLength": 256 }, "version": { "type": "string", "minLength": 1, "maxLength": 256 }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } } }, "additionalProperties": false }, "RoutePackRoute": { "type": "object", "required": [ "id", "name", "description", "targetModelId" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "maxLength": 2048 }, "targetModelId": { "type": "string", "description": "Generation-capable model this route can select once classifier routing is available." } }, "additionalProperties": false }, "RoutePackInput": { "type": "object", "required": [ "name", "fallbackModelId" ], "properties": { "id": { "type": "string", "description": "Optional stable internal ID. When omitted, the slug is used for new route packs and the existing ID is preserved for updates." }, "slug": { "type": "string", "description": "Optional body copy of the path slug. When present, it must match the path." }, "name": { "type": "string" }, "scope": { "$ref": "#/components/schemas/Scope" }, "enabled": { "type": "boolean" }, "fallbackModelId": { "type": "string" }, "routes": { "type": "array", "items": { "$ref": "#/components/schemas/RoutePackRoute" } }, "metadata": { "$ref": "#/components/schemas/RoutePackMetadata" } }, "additionalProperties": false }, "RoutePackActionInput": { "type": "object", "required": [ "action" ], "properties": { "action": { "$ref": "#/components/schemas/RoutePackAction" } }, "additionalProperties": false }, "RoutePackAction": { "type": "string", "enum": [ "validate" ] }, "RouterModelStatus": { "type": "string", "enum": [ "missing", "downloading", "ready", "failed", "disabled_by_policy" ] }, "RoutePackActionResult": { "type": "object", "required": [ "action", "accepted" ], "properties": { "action": { "$ref": "#/components/schemas/RoutePackAction" }, "accepted": { "type": "boolean" }, "messageKey": { "type": "string", "description": "Stable localization key for client-owned copy." }, "validation": { "$ref": "#/components/schemas/RoutePackValidationResult" } }, "additionalProperties": false }, "SmartRouteActionInput": { "type": "object", "required": [ "action" ], "properties": { "action": { "$ref": "#/components/schemas/SmartRouteAction" } }, "additionalProperties": false }, "SmartRouteAction": { "type": "string", "enum": [ "prepare_router" ] }, "SmartRouteBackendStatus": { "type": "string", "enum": [ "available", "needs_setup", "unsupported_platform" ] }, "SmartRouteBackendCandidate": { "type": "object", "required": [ "id", "serviceId", "kind", "status", "available" ], "properties": { "id": { "type": "string" }, "serviceId": { "type": "string" }, "kind": { "$ref": "#/components/schemas/ProviderKind" }, "status": { "$ref": "#/components/schemas/SmartRouteBackendStatus" }, "available": { "type": "boolean" }, "messageKey": { "type": "string", "description": "Stable localization key for client-owned copy." } }, "additionalProperties": false }, "SmartRouteStatus": { "type": "object", "required": [ "routerModelStatus" ], "properties": { "routerModelStatus": { "$ref": "#/components/schemas/RouterModelStatus" }, "selectedBackend": { "type": "string" }, "compatibleBackends": { "type": "array", "items": { "$ref": "#/components/schemas/SmartRouteBackendCandidate" } }, "activeJob": { "$ref": "#/components/schemas/Job" }, "messageKey": { "type": "string", "description": "Stable localization key for client-owned copy." } }, "additionalProperties": false }, "SmartRouteActionResult": { "type": "object", "required": [ "action", "accepted", "routerModelStatus" ], "properties": { "action": { "$ref": "#/components/schemas/SmartRouteAction" }, "accepted": { "type": "boolean" }, "routerModelStatus": { "$ref": "#/components/schemas/RouterModelStatus" }, "selectedBackend": { "type": "string" }, "compatibleBackends": { "type": "array", "items": { "$ref": "#/components/schemas/SmartRouteBackendCandidate" } }, "job": { "$ref": "#/components/schemas/Job" }, "messageKey": { "type": "string", "description": "Stable localization key for client-owned copy." } }, "additionalProperties": false }, "RoutePackValidationResult": { "type": "object", "required": [ "action", "valid", "messageKey", "warnings", "endpointFamilies" ], "properties": { "action": { "$ref": "#/components/schemas/RoutePackAction" }, "valid": { "type": "boolean" }, "messageKey": { "type": "string" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/RoutePackValidationWarning" } }, "endpointFamilies": { "type": "array", "items": { "$ref": "#/components/schemas/EndpointFamily" } } }, "additionalProperties": false }, "RoutePackValidationWarning": { "type": "object", "required": [ "code", "messageKey" ], "properties": { "code": { "type": "string", "enum": [ "ROUTER_MODEL_MISSING", "ROUTE_PACK_EMPTY_ROUTES", "ROUTE_PACK_FALLBACK_MODEL_UNAVAILABLE", "ROUTE_PACK_ROUTE_TARGET_MODEL_UNAVAILABLE" ] }, "messageKey": { "type": "string" }, "field": { "type": "string" }, "routeId": { "type": "string" } }, "additionalProperties": false }, "RoutingPolicy": { "type": "object", "required": [ "preferLocal", "allowFallbacks", "allowPaidFallback" ], "properties": { "preferLocal": { "type": "boolean" }, "allowFallbacks": { "type": "boolean", "description": "Fallbacks are schema-ready but rejected when true by the initial API behavior." }, "allowPaidFallback": { "type": "boolean", "description": "Paid fallbacks are schema-ready but rejected when true by the initial API behavior." } } }, "Service": { "type": "object", "required": [ "id", "name", "kind", "state", "managed" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "$ref": "#/components/schemas/ProviderKind" }, "state": { "type": "string", "enum": [ "stopped", "running", "unknown" ] }, "baseUrl": { "type": "string" }, "managed": { "type": "boolean" }, "enabled": { "type": "boolean", "description": "Whether Nexus automation may act on this service. Disabled services are never auto-started and the gateway rejects traffic routed to them with SERVICE_DISABLED; installed runtime versions and catalog records are preserved." }, "metadata": { "type": "object", "description": "Runtime metadata. Live service probes write machine-readable details under statusProbe and executableProbe. executableProbe reports only the cataloged executable name and availability from the active managed install or PATH, not the resolved local path or raw lookup error.", "additionalProperties": true } } }, "ServiceDiagnostics": { "type": "object", "description": "Path-safe troubleshooting view for one local runtime service. It does not expose arbitrary service metadata, local modelsDir values, resolved executable paths, configured runtime roots, generated artifact paths, credential references, raw network errors, or upstream response bodies.", "required": [ "serviceId", "name", "kind", "state", "managed", "cataloged", "actions" ], "properties": { "serviceId": { "type": "string" }, "name": { "type": "string" }, "kind": { "$ref": "#/components/schemas/ProviderKind" }, "state": { "type": "string", "enum": [ "stopped", "running", "unknown" ] }, "baseUrl": { "type": "string" }, "managed": { "type": "boolean" }, "cataloged": { "type": "boolean" }, "defaultPort": { "type": "integer", "minimum": 1, "maximum": 65535 }, "endpointFamilies": { "type": "array", "items": { "$ref": "#/components/schemas/EndpointFamily" } }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceActionSupport" } }, "executable": { "$ref": "#/components/schemas/ServiceExecutableDiagnostics" }, "statusProbe": { "$ref": "#/components/schemas/ServiceStatusProbeDiagnostics" }, "runtimeInstall": { "$ref": "#/components/schemas/ServiceRuntimeInstallDiagnostics" }, "config": { "$ref": "#/components/schemas/ServiceConfigDiagnostics" }, "managedVersions": { "type": "array", "items": { "$ref": "#/components/schemas/RuntimeVersion" } } }, "additionalProperties": false }, "ServiceActionSupport": { "type": "object", "required": [ "action", "supported" ], "properties": { "action": { "$ref": "#/components/schemas/ServiceAction" }, "supported": { "type": "boolean" }, "jobKind": { "type": "string" }, "requiresManagedProcess": { "type": "boolean", "description": "True for actions that Nexus can only run against a process it started and tracks." } }, "additionalProperties": false }, "ServiceExecutableDiagnostics": { "type": "object", "required": [ "name", "checked", "available" ], "properties": { "name": { "type": "string", "description": "Cataloged executable name, not the resolved local path." }, "checked": { "type": "boolean" }, "available": { "type": "boolean" }, "kind": { "type": "string", "description": "Stable lookup category such as path_lookup or not_found; raw lookup errors are omitted." } }, "additionalProperties": false }, "ServiceStatusProbeDiagnostics": { "type": "object", "description": "Allow-listed live status probe metadata. Raw transport errors and arbitrary upstream response fields are omitted.", "properties": { "kind": { "type": "string" }, "statusCode": { "type": "integer" }, "ready": { "type": "boolean" }, "version": { "type": "string" }, "runtimeStatus": { "type": "string" } }, "additionalProperties": false }, "ServiceRuntimeInstallDiagnostics": { "type": "object", "description": "Public-safe install state. Managed executablePath is relative to the validated archive root; absolute install directories are omitted.", "required": [ "strategy", "executable" ], "properties": { "strategy": { "type": "string", "enum": [ "path", "managed" ] }, "executable": { "type": "string" }, "runtimeVersion": { "type": "string" }, "releaseVersion": { "type": "string" }, "backend": { "type": "string", "enum": [ "automatic", "cpu", "metal", "cuda", "rocm", "vulkan", "sycl" ] }, "executablePath": { "type": "string", "description": "Validated relative archive path for Nexus-managed runtime installs. Absolute paths are omitted." }, "lastAction": { "$ref": "#/components/schemas/ServiceAction" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "ServiceConfigDiagnostics": { "type": "object", "description": "Presence flags for local service configuration. Values such as modelsDir are intentionally not returned.", "required": [ "modelsDirConfigured" ], "properties": { "modelsDirConfigured": { "type": "boolean" } }, "additionalProperties": false }, "RuntimeVersionList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RuntimeVersion" } } }, "additionalProperties": false }, "RuntimeVersion": { "type": "object", "required": [ "serviceId", "runtimeVersion", "active" ], "description": "Public-safe identity of one Nexus-managed runtime version. It intentionally excludes the runtime root, executable path, archive source URL, and uncataloged local directories.", "properties": { "serviceId": { "type": "string", "description": "Cataloged runtime service ID such as ollama, llamacpp, or mlx." }, "runtimeVersion": { "type": "string", "description": "Opaque promoted runtime variant ID used for rollback selection. Backend-specific builds of the same release have different IDs." }, "releaseVersion": { "type": "string", "description": "Publisher release version shared by backend variants." }, "backend": { "type": "string", "enum": [ "automatic", "cpu", "metal", "cuda", "rocm", "vulkan", "sycl" ] }, "active": { "type": "boolean", "description": "True when the service record currently points at this managed runtime version. This is derived from runtimeInstall metadata and is not a process-health signal." } }, "additionalProperties": false }, "RuntimeUpdate": { "type": "object", "required": [ "object", "serviceId", "status", "updateAvailable", "installAvailable" ], "description": "Runtime-owned update availability for one local runtime service. It contains only safe version and policy facts and intentionally excludes feed URLs, manifest URLs, trust keys, artifact URLs, local paths, and raw upstream errors.", "properties": { "object": { "type": "string", "const": "msty.nexus.runtime_update" }, "serviceId": { "type": "string" }, "runtimeId": { "type": "string" }, "status": { "$ref": "#/components/schemas/RuntimeUpdateStatus" }, "updateAvailable": { "type": "boolean" }, "installAvailable": { "type": "boolean" }, "currentVersion": { "type": "string", "description": "Current managed runtime version from service metadata when Nexus owns the install." }, "latestVersion": { "type": "string", "description": "Latest allowed version selected by Runtime policy for this service and platform." }, "channel": { "type": "string", "description": "Runtime release channel such as stable when the configured source supports channels." }, "source": { "type": "string", "description": "Runtime install policy source used for the check, such as feed, manifest, upstream, path, or disabled." }, "checkedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "RuntimeUpdateStatus": { "type": "string", "enum": [ "update_available", "current", "installable", "external", "disabled", "unsupported", "unavailable" ] }, "ServiceActionRequest": { "type": "object", "required": [ "action" ], "properties": { "action": { "$ref": "#/components/schemas/ServiceAction" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "description": "Optional requested runtime port for actions such as install, update, start, or restart. Stop, rollback, and uninstall reject port because they must not rewrite the stored runtime endpoint. Start rejects a different port while a Nexus-managed process is already running; use restart to change ports. When supplied, Nexus stores a loopback service baseUrl for status probes." }, "runtimeVersion": { "type": "string", "description": "Required for rollback actions and rejected for other actions. The value is a retained Nexus-managed runtime version identifier after single-path-segment validation, never a local path." }, "backend": { "type": "string", "enum": ["automatic", "cpu", "metal", "cuda", "rocm", "vulkan", "sycl"], "description": "Optional managed runtime package variant for install or update. Omit it or use automatic to let Nexus choose from backends that passed host readiness checks. This does not replace per-model GPU placement controls. Other service actions reject this field." }, "metadata": { "type": "object", "description": "Reserved for future allow-listed runtime configuration. Current public runtime actions do not accept client-supplied storage paths.", "additionalProperties": false, "properties": {} } }, "additionalProperties": false }, "ServiceAction": { "type": "string", "enum": [ "install", "start", "stop", "restart", "update", "rollback", "uninstall", "disable", "enable" ] }, "Job": { "type": "object", "required": [ "id", "kind", "state", "progress" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "state": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "metadata": { "type": "object", "description": "Read-side allow-listed job metadata. Restart-interrupted jobs use errorCode JOB_INTERRUPTED. Cluster setup failures can include failedMemberId and failedMemberIds when Nexus can safely identify the machines that need attention.", "additionalProperties": true } } }, "AuditActorType": { "type": "string", "enum": [ "system", "local_token" ] }, "AuditResourceType": { "type": "string", "enum": [ "provider", "model", "preset", "route_pack", "smart_route", "token", "service", "job", "settings", "gauge", "pairing_request" ] }, "AuditAction": { "type": "string", "enum": [ "provider.created", "provider.updated", "provider.deleted", "model.created", "model.updated", "model.deleted", "preset.created", "preset.updated", "preset.deleted", "route_pack.created", "route_pack.updated", "route_pack.deleted", "route_pack.validated", "smart_route.prepare_requested", "token.created", "token.updated", "token.deleted", "job.queued", "job.cancelled", "job.cleared", "settings.updated", "gauge.source.updated", "gauge.account.created", "gauge.account.updated", "gauge.account.deleted", "gauge.history.deleted", "pairing.approved", "pairing.denied", "pairing.callback_failed", "service.account_added", "service.account_removed" ] }, "Scope": { "type": "string", "enum": [ "local", "account", "team" ] }, "ClusterTopology": { "type": "object", "required": [ "object", "formed", "nodes" ], "properties": { "object": { "type": "string" }, "formed": { "type": "boolean" }, "mode": { "type": "string" }, "backend": { "type": "string" }, "model": { "type": "string" }, "degraded": { "type": "boolean" }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/ClusterNode" } } } }, "ClusterNode": { "type": "object", "required": [ "memberId", "rank", "role", "online" ], "properties": { "memberId": { "type": "string" }, "rank": { "type": "integer" }, "role": { "type": "string" }, "online": { "type": "boolean" } } }, "ClusterDiscoveryNode": { "type": "object", "description": "One member's public-safe discovery status: reachability, RDMA state, and the opaque member IDs it has a direct Thunderbolt cable to. Never exposes interface names or UUIDs.", "required": [ "memberId", "reachable", "rdmaEnabled" ], "properties": { "memberId": { "type": "string" }, "reachable": { "type": "boolean" }, "rdmaEnabled": { "type": "boolean" }, "linkedTo": { "type": "array", "items": { "type": "string" } } } }, "ClusterDiscovery": { "type": "object", "description": "Public-safe result of probing every member's cluster fabric before forming: per-node RDMA state and Thunderbolt links, plus whether the set forms a complete, formable jaccl mesh. Carries no IP addresses, hostnames, RDMA device names, or Thunderbolt UUIDs \u2014 opaque member IDs only.", "required": [ "object", "meshComplete", "formable", "nodes" ], "properties": { "object": { "type": "string" }, "meshComplete": { "type": "boolean" }, "formable": { "type": "boolean" }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/ClusterDiscoveryNode" } } } }, "ClusterLinkCommand": { "type": "object", "description": "One validated Thunderbolt-IP link setup step the root link helper applies: bring an interface up with its /30 address and pin the peer's address to it. The member re-validates these before its helper runs them.", "required": [ "interface", "address", "peerAddress", "netmask" ], "properties": { "interface": { "type": "string" }, "address": { "type": "string" }, "peerAddress": { "type": "string" }, "netmask": { "type": "string" } } }, "ClusterMember": { "type": "object", "description": "One configured cluster machine as shown to the operator's app. This management surface intentionally includes the operator-entered host (their own configuration, like a provider base URL); it is not the public host-free topology.", "required": [ "id", "host", "baseUrl" ], "properties": { "id": { "type": "string" }, "host": { "type": "string" }, "baseUrl": { "type": "string" } } }, "ClusterMembers": { "type": "object", "required": [ "object", "members" ], "properties": { "object": { "type": "string" }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/ClusterMember" } } } }, "ClusterAddMember": { "type": "object", "description": "Adds a cluster machine by hostname or IP literal and Runtime port. The server assigns the opaque member ID and derives the control URL. Host must not include a scheme, path, query string, credentials, or port.", "required": [ "host", "port" ], "properties": { "host": { "type": "string", "description": "Hostname or IP literal only. Do not include a scheme, path, query string, credentials, or port." }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 } } }, "ClusterPrepareModel": { "type": "object", "description": "Requests cluster-wide MLX model cache preparation before formation. The model must be an owner/repo-style Hugging Face model ID and must not include leading or trailing whitespace.", "required": [ "model" ], "properties": { "model": { "type": "string", "description": "Path-safe Hugging Face owner/repo model ID to cache on every member.", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:\\[\\]-]*/[A-Za-z0-9][A-Za-z0-9._:\\[\\]-]*(/[A-Za-z0-9][A-Za-z0-9._:\\[\\]-]*)*$" } } }, "ClusterWorkerSpec": { "type": "object", "description": "Per-member instruction to launch one MLX cluster worker (a rank in the distributed group). The controller sends it to a member over the LAN. It carries only rank wiring, never controller secrets; the RDMA device matrix and bind host are inter-rank transport details, not part of the public host-free topology.", "required": [ "model", "mode", "backend", "rank", "isCoordinator", "bindHost", "apiPort", "ringPort", "env", "rdmaDeviceMatrix" ], "properties": { "model": { "type": "string", "minLength": 1 }, "mode": { "type": "string", "enum": [ "pipeline", "tensor" ] }, "backend": { "type": "string", "enum": [ "jaccl" ] }, "rank": { "type": "integer", "minimum": 0 }, "isCoordinator": { "type": "boolean" }, "bindHost": { "type": "string", "minLength": 1 }, "apiPort": { "type": "integer", "minimum": 1, "maximum": 65535 }, "ringPort": { "type": "integer", "minimum": 1, "maximum": 65535 }, "env": { "type": "object", "description": "Inline MLX rank environment produced by the controller. MLX_RANK must match rank, and MLX_JACCL_COORDINATOR must be the rank-0 host:port produced with standard host-port formatting.", "required": [ "MLX_RANK", "MLX_JACCL_COORDINATOR" ], "properties": { "MLX_RANK": { "type": "string" }, "MLX_JACCL_COORDINATOR": { "type": "string", "minLength": 1 } }, "additionalProperties": { "type": "string" } }, "rdmaDeviceMatrix": { "type": "array", "description": "Square rank-by-rank jaccl ibverbs device matrix. It must contain at least two ranks; non-self peer links must name a device.", "minItems": 2, "items": { "type": "array", "minItems": 2, "items": { "type": "string" } } } } }, "ClusterThunderboltPort": { "type": "object", "description": "One Thunderbolt port on a member: its OS interface name, its own Thunderbolt domain UUID, and the UUID of the port it is cabled to (omitted when nothing is plugged in). The controller matches one node's connectedToUuid against another's uuid to find direct cables.", "required": [ "interface", "uuid" ], "properties": { "interface": { "type": "string" }, "uuid": { "type": "string" }, "connectedToUuid": { "type": "string" } } }, "ClusterNodeCapability": { "type": "object", "description": "A member's self-reported cluster-fabric capability: its RDMA (ibverbs) devices and Thunderbolt wiring. An internal Runtime-to-Runtime payload the controller collects from every member to assemble the jaccl mesh; it carries device and port identifiers, never controller secrets, and is never the public host-free topology. Empty rdmaDevices means RDMA is not enabled on that node yet.", "properties": { "rdmaDevices": { "type": "array", "items": { "type": "string" } }, "thunderboltPorts": { "type": "array", "items": { "$ref": "#/components/schemas/ClusterThunderboltPort" } } } }, "ClusterWorkerState": { "type": "object", "description": "Public-safe status of a member's local cluster worker process. Carries no host or path detail.", "required": [ "running", "rank" ], "properties": { "running": { "type": "boolean" }, "model": { "type": "string" }, "rank": { "type": "integer" } } }, "ProviderKind": { "type": "string", "enum": [ "openai", "anthropic", "openrouter", "openai-compatible-local", "ollama", "llamacpp", "mlx", "cliproxy", "cluster" ] }, "RuntimeDiscoveryStatus": { "type": "string", "enum": [ "ready", "already_registered", "unreachable", "invalid_response" ] }, "ProviderAction": { "type": "string", "enum": [ "check" ] }, "ProviderCheckStatus": { "type": "string", "enum": [ "ready", "disabled", "missing_credential", "invalid_configuration", "rejected", "unreachable", "invalid_response", "unsupported" ] }, "ModelRegistrySource": { "type": "string", "enum": [ "huggingface", "ollama" ] }, "EndpointFamily": { "type": "string", "enum": [ "openai.chat_completions", "openai.embeddings", "openai.responses", "anthropic.messages", "openai.images", "openai.audio_speech", "openai.audio_transcriptions", "rerank.documents" ] }, "PairingRequestInput": { "type": "object", "required": [ "clientName", "callbackUrl", "state" ], "properties": { "clientName": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Display name for the local native client asking the user for access." }, "clientId": { "type": "string", "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "description": "Optional stable native client identifier for audit metadata, such as a reverse-DNS app ID." }, "callbackUrl": { "type": "string", "format": "uri", "description": "Loopback HTTP callback URL using a literal 127.0.0.1 or ::1 address and explicit port. It must not contain URL credentials. Nexus sends the grant only in a POST body after user approval." }, "state": { "type": "string", "minLength": 16, "maxLength": 256, "pattern": "^[A-Za-z0-9._~-]{16,256}$", "description": "Opaque requester nonce returned only to the callback so the client can match the approval to its original request." } }, "additionalProperties": false }, "PairingRequest": { "type": "object", "required": [ "object", "id", "clientName", "scope", "code", "callbackHost", "callbackPort", "createdAt", "expiresAt" ], "properties": { "object": { "type": "string", "const": "msty.nexus.pairing_request" }, "id": { "type": "string" }, "clientName": { "type": "string" }, "clientId": { "type": "string" }, "scope": { "$ref": "#/components/schemas/Scope" }, "code": { "type": "string", "pattern": "^\\d{3}-\\d{3}$", "description": "Short confirmation code shown by both apps so the user can match the request." }, "callbackHost": { "type": "string", "description": "Loopback callback host only. The callback path, query, and state are not exposed in list responses." }, "callbackPort": { "type": "integer", "minimum": 1, "maximum": 65535 }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "PairingRequestList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PairingRequest" } } } }, "PairingDecisionResponse": { "type": "object", "required": [ "object", "requestId", "approved", "delivered" ], "properties": { "object": { "type": "string", "const": "msty.nexus.pairing_decision" }, "requestId": { "type": "string" }, "approved": { "type": "boolean" }, "delivered": { "type": "boolean", "description": "True only when an approved token was delivered to the requester callback." }, "record": { "$ref": "#/components/schemas/Token" } }, "additionalProperties": false }, "PairingGrant": { "type": "object", "required": [ "object", "requestId", "state", "runtimeBaseUrl", "token", "tokenType", "scope" ], "properties": { "object": { "type": "string", "const": "msty.nexus.pairing_grant" }, "requestId": { "type": "string" }, "state": { "type": "string", "description": "Opaque requester nonce from the original pairing request." }, "runtimeBaseUrl": { "type": "string", "format": "uri" }, "token": { "type": "string", "writeOnly": true, "description": "Plaintext local Nexus token delivered only to the requester callback POST body after user approval." }, "tokenType": { "type": "string", "const": "Bearer" }, "scope": { "$ref": "#/components/schemas/Scope" } }, "additionalProperties": false }, "UsageGroupBy": { "type": "string", "description": "Usage breakdown dimension. token groups by the local Nexus token that authenticated each request, which is the closest stable notion of a client application.", "enum": [ "provider", "model", "providerModel", "token" ] }, "UsageSummary": { "type": "object", "description": "Aggregate usage counters for one local-day range. Counters come from provider-reported usage objects; requests whose providers did not report usage contribute zero tokens.", "required": [ "object", "from", "to", "requests", "failedRequests", "inputTokens", "outputTokens", "totalTokens", "toolCalls" ], "properties": { "object": { "type": "string", "const": "msty.nexus.usage_summary" }, "from": { "type": "string", "format": "date", "description": "Effective inclusive first local day." }, "to": { "type": "string", "format": "date", "description": "Effective inclusive last local day." }, "requests": { "type": "integer", "description": "Gateway generation requests that reached a provider." }, "failedRequests": { "type": "integer", "description": "Requests that failed upstream or did not complete their relay." }, "inputTokens": { "type": "integer" }, "outputTokens": { "type": "integer" }, "totalTokens": { "type": "integer" }, "toolCalls": { "type": "integer", "description": "Total tool invocations the models requested." } }, "additionalProperties": false }, "UsageDailyBucket": { "type": "object", "required": [ "day", "requests", "failedRequests", "inputTokens", "outputTokens", "totalTokens", "toolCalls" ], "properties": { "day": { "type": "string", "format": "date", "description": "Local day bucket (YYYY-MM-DD) assigned when the request was recorded." }, "requests": { "type": "integer", "description": "Gateway generation requests that reached a provider." }, "failedRequests": { "type": "integer", "description": "Requests that failed upstream or did not complete their relay." }, "inputTokens": { "type": "integer" }, "outputTokens": { "type": "integer" }, "totalTokens": { "type": "integer" }, "toolCalls": { "type": "integer", "description": "Total tool invocations the models requested." } }, "additionalProperties": false }, "UsageDailyList": { "type": "object", "required": [ "from", "to", "data" ], "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/UsageDailyBucket" } } }, "additionalProperties": false }, "UsageBreakdownRow": { "type": "object", "description": "One ranked aggregation group. Only the fields matching the requested groupBy dimension are populated.", "required": [ "requests", "failedRequests", "inputTokens", "outputTokens", "totalTokens", "toolCalls" ], "properties": { "providerId": { "type": "string" }, "modelId": { "type": "string" }, "tokenId": { "type": "string", "description": "Local Nexus token ID. Token values are never exposed." }, "requests": { "type": "integer", "description": "Gateway generation requests that reached a provider." }, "failedRequests": { "type": "integer", "description": "Requests that failed upstream or did not complete their relay." }, "inputTokens": { "type": "integer" }, "outputTokens": { "type": "integer" }, "totalTokens": { "type": "integer" }, "toolCalls": { "type": "integer", "description": "Total tool invocations the models requested." } }, "additionalProperties": false }, "UsageBreakdownList": { "type": "object", "required": [ "from", "to", "groupBy", "data" ], "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "groupBy": { "$ref": "#/components/schemas/UsageGroupBy" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/UsageBreakdownRow" } } }, "additionalProperties": false }, "UsageToolRow": { "type": "object", "required": [ "toolName", "calls", "requests" ], "properties": { "toolName": { "type": "string", "description": "Caller-defined tool name observed in model responses." }, "calls": { "type": "integer", "description": "Total times models requested this tool." }, "requests": { "type": "integer", "description": "Requests in which this tool appeared at least once." } }, "additionalProperties": false }, "UsageToolList": { "type": "object", "required": [ "from", "to", "data" ], "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/UsageToolRow" } } }, "additionalProperties": false }, "UsageRouteRow": { "type": "object", "description": "One Smart Route aggregate row. Route fields are stable IDs and reason codes only; prompt text, classifier output, and route descriptions are never represented.", "required": [ "routePackSlug", "routeFallback", "requests", "failedRequests", "fallbackRequests", "inputTokens", "outputTokens", "totalTokens", "toolCalls" ], "properties": { "routePackSlug": { "type": "string", "description": "Route pack slug requested through the @route/{slug} synthetic model." }, "routeSelectedRouteId": { "type": "string", "description": "Stable route ID selected by Smart Route when a non-fallback route matched." }, "resolvedModelId": { "type": "string", "description": "Resolved catalog model ID invoked after routing." }, "providerId": { "type": "string" }, "routeFallback": { "type": "boolean" }, "routeFallbackReason": { "type": "string", "description": "Stable fallback reason code when fallback routing was used." }, "requests": { "type": "integer", "description": "Gateway generation requests that reached a provider." }, "failedRequests": { "type": "integer", "description": "Requests that failed upstream or did not complete their relay." }, "fallbackRequests": { "type": "integer", "description": "Requests in this row that used the route pack fallback." }, "inputTokens": { "type": "integer" }, "outputTokens": { "type": "integer" }, "totalTokens": { "type": "integer" }, "toolCalls": { "type": "integer", "description": "Total tool invocations the models requested." } }, "additionalProperties": false }, "UsageRouteList": { "type": "object", "required": [ "from", "to", "data" ], "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/UsageRouteRow" } } }, "additionalProperties": false }, "UsageAccelerationSummary": { "type": "object", "description": "Aggregate acceleration counters for one local-day range. Speedup and time-saved fields are omitted when no same-model non-accelerated baseline is available. Draft acceptance fields are omitted when the runtime did not report draft counters.", "required": [ "requests", "acceleratedRequests", "acceleratedTokens", "acceleratedOutputTokens", "durationMs" ], "properties": { "requests": { "type": "integer", "format": "int64", "description": "All requests represented by the acceleration aggregation, including non-accelerated baseline rows." }, "acceleratedRequests": { "type": "integer", "format": "int64", "description": "Requests that used an acceleration mode other than off." }, "acceleratedTokens": { "type": "integer", "format": "int64", "description": "Total tokens from accelerated requests." }, "acceleratedOutputTokens": { "type": "integer", "format": "int64", "description": "Output tokens from accelerated requests." }, "durationMs": { "type": "integer", "format": "int64", "description": "Observed generation duration for accelerated requests when available." }, "baselineDurationMs": { "type": "integer", "format": "int64", "description": "Estimated non-accelerated duration for comparable accelerated output tokens." }, "tokensPerSecond": { "type": "number", "format": "double" }, "baselineTokensPerSecond": { "type": "number", "format": "double" }, "speedup": { "type": "number", "format": "double", "description": "Accelerated tokens per second divided by comparable baseline tokens per second." }, "estimatedTimeSavedMs": { "type": "integer", "format": "int64" }, "fallbackRequests": { "type": "integer", "format": "int64" }, "draftAcceptedTokens": { "type": "integer", "format": "int64" }, "draftProposedTokens": { "type": "integer", "format": "int64" }, "acceptanceRate": { "type": "number", "format": "double" } }, "additionalProperties": false }, "UsageAccelerationRow": { "type": "object", "description": "One acceleration aggregate row grouped by provider, resolved model, preset slug, mode, and draft model ID. IDs are stable catalog IDs only.", "required": [ "mode", "requests", "failedRequests", "inputTokens", "outputTokens", "totalTokens", "durationMs" ], "properties": { "providerId": { "type": "string" }, "modelId": { "type": "string" }, "presetSlug": { "type": "string", "description": "Preset slug when the accelerated request used a preset-owned acceleration profile." }, "mode": { "$ref": "#/components/schemas/AccelerationMode" }, "draftModelId": { "type": "string" }, "requests": { "type": "integer", "format": "int64", "description": "Gateway generation requests that reached a provider." }, "failedRequests": { "type": "integer", "format": "int64", "description": "Requests that failed upstream or did not complete their relay." }, "inputTokens": { "type": "integer", "format": "int64" }, "outputTokens": { "type": "integer", "format": "int64" }, "totalTokens": { "type": "integer", "format": "int64" }, "durationMs": { "type": "integer", "format": "int64" }, "baselineDurationMs": { "type": "integer", "format": "int64" }, "tokensPerSecond": { "type": "number", "format": "double" }, "baselineTokensPerSecond": { "type": "number", "format": "double" }, "speedup": { "type": "number", "format": "double" }, "estimatedTimeSavedMs": { "type": "integer", "format": "int64" }, "fallbackRequests": { "type": "integer", "format": "int64" }, "draftAcceptedTokens": { "type": "integer", "format": "int64" }, "draftProposedTokens": { "type": "integer", "format": "int64" }, "acceptanceRate": { "type": "number", "format": "double" } }, "additionalProperties": false }, "UsageAccelerationList": { "type": "object", "required": [ "object", "from", "to", "summary", "data" ], "properties": { "object": { "type": "string", "const": "msty.nexus.usage_acceleration" }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "summary": { "$ref": "#/components/schemas/UsageAccelerationSummary" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/UsageAccelerationRow" } } }, "additionalProperties": false }, "SettingsUsage": { "type": "object", "description": "Effective local usage-metrics posture. Usage rows hold token counters and stable IDs only; prompt text, response text, tool arguments, headers, and credentials are never recorded.", "required": [ "trackingEnabled", "retentionDays" ], "properties": { "trackingEnabled": { "type": "boolean", "description": "True when gateway usage capture is recording events. Defaults to true." }, "retentionDays": { "type": "integer", "minimum": 1, "maximum": 3650, "description": "Days of raw usage events retained before automatic pruning. Defaults to 365." } }, "additionalProperties": false }, "SettingsUsagePatch": { "type": "object", "description": "Usage metrics settings update. At least one field is required.", "minProperties": 1, "properties": { "trackingEnabled": { "type": "boolean" }, "retentionDays": { "type": "integer", "minimum": 1, "maximum": 3650 } }, "additionalProperties": false }, "SettingsGauge": { "type": "object", "description": "Effective posture for the optional Gauge feature. Gauge is off by default, so no provider collection runs until enabled.", "required": [ "enabled", "retentionDays" ], "properties": { "enabled": { "type": "boolean", "description": "True after the user opts into Gauge." }, "retentionDays": { "type": "integer", "minimum": 1, "maximum": 3650, "description": "Days of normalized Gauge snapshots retained before automatic pruning. Defaults to 365." } }, "additionalProperties": false }, "SettingsGaugePatch": { "type": "object", "description": "Gauge settings update. At least one field is required.", "minProperties": 1, "properties": { "enabled": { "type": "boolean" }, "retentionDays": { "type": "integer", "minimum": 1, "maximum": 3650 } }, "additionalProperties": false }, "GaugeSourceKind": { "type": "string", "enum": [ "gateway", "subscription", "billing" ] }, "GaugeAuthMode": { "type": "string", "enum": [ "none", "local_session", "api_key", "admin_key", "oauth", "device_flow", "browser_session", "cli", "local_file", "custom_endpoint", "aws_credentials" ] }, "GaugeSourceStatus": { "type": "string", "enum": [ "disabled", "ready", "refreshing", "stale", "needs_auth", "error", "unavailable" ] }, "GaugeCapability": { "type": "string", "enum": [ "limits", "costs", "usage", "health", "balance", "credits", "attribution", "provider_status", "multiple_accounts", "account_switching", "actions", "alerts", "storage", "diagnostics" ] }, "GaugeForecastState": { "type": "string", "enum": [ "unknown", "on_pace", "reserve", "at_risk", "exhausted" ] }, "GaugeHealthState": { "type": "string", "enum": [ "unknown", "healthy", "degraded", "incident" ] }, "GaugeQuotaCategory": { "type": "string", "enum": ["session", "daily", "weekly", "monthly", "model", "credits", "requests", "tokens", "spend", "custom"] }, "GaugeResetKind": { "type": "string", "enum": ["unknown", "fixed", "rolling", "calendar", "manual"] }, "GaugeProvenanceKind": { "type": "string", "enum": ["provider_reported", "locally_observed", "estimated", "forecast"] }, "GaugeConfidence": { "type": "string", "enum": ["unknown", "low", "medium", "high"] }, "GaugeCreditKind": { "type": "string", "enum": ["balance", "grant", "bonus", "overage", "reset_credit", "invoice"] }, "GaugeAttributionDimension": { "type": "string", "enum": ["provider", "account", "model", "project", "workspace", "source", "session"] }, "GaugeProviderStatusState": { "type": "string", "enum": ["unknown", "operational", "degraded", "outage", "maintenance"] }, "GaugeIncidentSeverity": { "type": "string", "enum": ["info", "minor", "major", "critical"] }, "GaugeActionKind": { "type": "string", "enum": ["open_usage", "open_billing", "open_status", "buy_credits", "reconnect", "switch_account"] }, "GaugeConfigFieldKind": { "type": "string", "enum": ["text", "secret", "url", "choice", "boolean"] }, "GaugeIdentity": { "type": "object", "properties": { "displayLabel": {"type": "string", "maxLength": 320}, "organizationLabel": {"type": "string", "maxLength": 320} }, "additionalProperties": false }, "GaugeCredit": { "type": "object", "required": ["id", "kind", "unit"], "properties": { "id": {"type": "string", "maxLength": 160}, "label": {"type": "string", "maxLength": 160}, "kind": {"$ref": "#/components/schemas/GaugeCreditKind"}, "unit": {"type": "string", "maxLength": 32}, "available": {"type": "number"}, "granted": {"type": "number"}, "used": {"type": "number"}, "limit": {"type": "number"}, "grantedAt": {"type": "string", "format": "date-time"}, "expiresAt": {"type": "string", "format": "date-time"}, "resetsAt": {"type": "string", "format": "date-time"} }, "additionalProperties": false }, "GaugeAttribution": { "type": "object", "description": "One flat provider/account/model/project/workspace/source/session attribution row.", "required": ["id", "dimension", "label", "usage"], "properties": { "id": {"type": "string", "maxLength": 160}, "parentId": {"type": "string", "maxLength": 160}, "dimension": {"$ref": "#/components/schemas/GaugeAttributionDimension"}, "label": {"type": "string", "maxLength": 320}, "usage": {"$ref": "#/components/schemas/GaugeUsage"}, "actualCostUsd": {"type": "number"}, "estimatedCostUsd": {"type": "number"} }, "additionalProperties": false }, "GaugeStatusComponent": { "type": "object", "required": ["id", "label", "state"], "properties": { "id": {"type": "string", "maxLength": 160}, "label": {"type": "string", "maxLength": 320}, "state": {"$ref": "#/components/schemas/GaugeProviderStatusState"}, "updatedAt": {"type": "string", "format": "date-time"} }, "additionalProperties": false }, "GaugeIncident": { "type": "object", "required": ["id", "title", "severity", "state"], "properties": { "id": {"type": "string", "maxLength": 160}, "title": {"type": "string", "maxLength": 320}, "severity": {"$ref": "#/components/schemas/GaugeIncidentSeverity"}, "state": {"type": "string", "maxLength": 80}, "componentIds": {"type": "array", "maxItems": 128, "items": {"type": "string", "maxLength": 160}}, "startedAt": {"type": "string", "format": "date-time"}, "updatedAt": {"type": "string", "format": "date-time"} }, "additionalProperties": false }, "GaugeProviderStatus": { "type": "object", "required": ["state", "observedAt", "components", "incidents"], "properties": { "state": {"$ref": "#/components/schemas/GaugeProviderStatusState"}, "observedAt": {"type": "string", "format": "date-time"}, "components": {"type": "array", "maxItems": 128, "items": {"$ref": "#/components/schemas/GaugeStatusComponent"}}, "incidents": {"type": "array", "maxItems": 64, "items": {"$ref": "#/components/schemas/GaugeIncident"}}, "actionId": {"type": "string", "maxLength": 160} }, "additionalProperties": false }, "GaugeProvenance": { "type": "object", "required": ["metric", "kind", "confidence", "complete"], "properties": { "metric": {"type": "string", "maxLength": 160}, "kind": {"$ref": "#/components/schemas/GaugeProvenanceKind"}, "sourceLabel": {"type": "string", "maxLength": 320}, "observedAt": {"type": "string", "format": "date-time"}, "confidence": {"$ref": "#/components/schemas/GaugeConfidence"}, "complete": {"type": "boolean"}, "noteKey": {"type": "string", "maxLength": 240} }, "additionalProperties": false }, "GaugeActivityPoint": { "type": "object", "description": "One redacted activity bucket. Actual and estimated costs are distinct and completeness is explicit.", "required": ["id", "accountId", "providerId", "bucketStart", "bucketEnd", "usage", "provenance", "confidence", "complete"], "properties": { "id": {"type": "string", "maxLength": 160}, "accountId": {"type": "string", "maxLength": 160}, "providerId": {"type": "string", "maxLength": 160}, "bucketStart": {"type": "string", "format": "date-time"}, "bucketEnd": {"type": "string", "format": "date-time"}, "model": {"type": "string", "maxLength": 320}, "project": {"type": "string", "maxLength": 320}, "workspace": {"type": "string", "maxLength": 320, "description": "A redacted label, never an absolute local path."}, "source": {"type": "string", "maxLength": 160}, "session": {"type": "string", "maxLength": 320}, "usage": {"$ref": "#/components/schemas/GaugeUsage"}, "cachedInputTokens": {"type": "integer", "format": "int64", "minimum": 0}, "cacheWriteTokens": {"type": "integer", "format": "int64", "minimum": 0}, "reasoningTokens": {"type": "integer", "format": "int64", "minimum": 0}, "actualCostUsd": {"type": "number"}, "estimatedCostUsd": {"type": "number"}, "provenance": {"$ref": "#/components/schemas/GaugeProvenanceKind"}, "confidence": {"$ref": "#/components/schemas/GaugeConfidence"}, "complete": {"type": "boolean"} }, "additionalProperties": false }, "GaugeActivityResponse": { "type": "object", "required": ["object", "data", "hasMore"], "properties": { "object": {"type": "string", "const": "msty.nexus.gauge_activity"}, "data": {"type": "array", "maxItems": 200, "items": {"$ref": "#/components/schemas/GaugeActivityPoint"}}, "hasMore": {"type": "boolean"}, "nextOffset": {"type": "integer", "minimum": 1, "maximum": 1000200} }, "additionalProperties": false }, "GaugeReading": { "type": "object", "required": ["providerId", "accountId", "status", "snapshot"], "properties": { "providerId": {"type": "string", "maxLength": 160}, "accountId": {"type": "string", "maxLength": 160}, "status": {"$ref": "#/components/schemas/GaugeSourceStatus"}, "problemCode": {"type": "string", "maxLength": 160}, "snapshot": {"$ref": "#/components/schemas/GaugeSnapshot"} }, "additionalProperties": false }, "GaugeReadingsResponse": { "type": "object", "required": ["object", "data", "hasMore"], "properties": { "object": {"type": "string", "const": "msty.nexus.gauge_readings"}, "data": {"type": "array", "maxItems": 200, "items": {"$ref": "#/components/schemas/GaugeReading"}}, "hasMore": {"type": "boolean"}, "nextOffset": {"type": "integer", "minimum": 1, "maximum": 1000200} }, "additionalProperties": false }, "GaugeAccountReachability": { "type": "object", "required": ["accountId", "label", "status"], "properties": { "accountId": {"type": "string", "maxLength": 160}, "label": {"type": "string", "maxLength": 320}, "status": {"$ref": "#/components/schemas/GaugeSourceStatus"}, "problemCode": {"type": "string", "maxLength": 160}, "lastAttemptAt": {"type": "string", "format": "date-time"}, "lastSuccessAt": {"type": "string", "format": "date-time"} }, "additionalProperties": false }, "GaugeStatusSummary": { "type": "object", "required": ["providerId", "accounts"], "properties": { "providerId": {"type": "string", "maxLength": 160}, "status": {"$ref": "#/components/schemas/GaugeProviderStatus"}, "accounts": {"type": "array", "maxItems": 128, "items": {"$ref": "#/components/schemas/GaugeAccountReachability"}} }, "additionalProperties": false }, "GaugeStatusesResponse": { "type": "object", "required": ["object", "data"], "properties": { "object": {"type": "string", "const": "msty.nexus.gauge_statuses"}, "data": {"type": "array", "maxItems": 256, "items": {"$ref": "#/components/schemas/GaugeStatusSummary"}} }, "additionalProperties": false }, "GaugeRecommendationType": {"type": "string", "enum": ["account", "provider", "model"]}, "GaugeWorkEstimateOutcome": {"type": "string", "enum": ["likely", "tight", "unlikely", "unknown"]}, "GaugeRecommendation": { "type": "object", "required": ["id", "type", "reasonKeys", "score", "confidence", "generatedAt"], "properties": { "id": {"type": "string", "maxLength": 320}, "type": {"$ref": "#/components/schemas/GaugeRecommendationType"}, "accountId": {"type": "string", "maxLength": 160}, "providerId": {"type": "string", "maxLength": 160}, "model": {"type": "string", "maxLength": 320}, "reasonKeys": {"type": "array", "maxItems": 16, "items": {"type": "string", "maxLength": 240}}, "score": {"type": "number", "minimum": 0, "maximum": 100}, "remainingPercent": {"type": "number", "minimum": 0, "maximum": 100}, "forecastState": {"$ref": "#/components/schemas/GaugeForecastState"}, "estimatedCostUsd": {"type": "number", "minimum": 0}, "confidence": {"$ref": "#/components/schemas/GaugeConfidence"}, "generatedAt": {"type": "string", "format": "date-time"}, "dataFreshThrough": {"type": "string", "format": "date-time"} }, "additionalProperties": false }, "GaugeWorkEstimate": { "type": "object", "required": ["accountId", "providerId", "durationSeconds", "outcome", "confidence", "reasonKeys"], "properties": { "accountId": {"type": "string", "maxLength": 160}, "providerId": {"type": "string", "maxLength": 160}, "durationSeconds": {"type": "integer", "format": "int64", "minimum": 300, "maximum": 604800}, "outcome": {"$ref": "#/components/schemas/GaugeWorkEstimateOutcome"}, "confidence": {"$ref": "#/components/schemas/GaugeConfidence"}, "reasonKeys": {"type": "array", "maxItems": 16, "items": {"type": "string", "maxLength": 240}}, "limitingWindowId": {"type": "string", "maxLength": 160}, "remainingPercent": {"type": "number", "minimum": 0, "maximum": 100}, "projectedExhaustedAt": {"type": "string", "format": "date-time"}, "resetAt": {"type": "string", "format": "date-time"}, "dataFreshThrough": {"type": "string", "format": "date-time"} }, "additionalProperties": false }, "GaugeRecommendationsResponse": { "type": "object", "required": ["object", "data"], "properties": { "object": {"type": "string", "const": "msty.nexus.gauge_recommendations"}, "data": {"type": "array", "maxItems": 10, "items": {"$ref": "#/components/schemas/GaugeRecommendation"}}, "canFinish": {"$ref": "#/components/schemas/GaugeWorkEstimate"} }, "additionalProperties": false }, "GaugeCapacityState": {"type": "string", "enum": ["available", "caution", "constrained", "unknown"]}, "GaugeCapacitySignal": { "type": "object", "required": ["providerId", "accountId", "state", "score", "observedAt", "confidence", "reasonKeys"], "properties": { "providerId": {"type": "string", "maxLength": 160}, "accountId": {"type": "string", "maxLength": 160}, "state": {"$ref": "#/components/schemas/GaugeCapacityState"}, "score": {"type": "number", "minimum": 0, "maximum": 100}, "remainingPercent": {"type": "number", "minimum": 0, "maximum": 100}, "resetAt": {"type": "string", "format": "date-time"}, "observedAt": {"type": "string", "format": "date-time"}, "confidence": {"$ref": "#/components/schemas/GaugeConfidence"}, "reasonKeys": {"type": "array", "maxItems": 8, "items": {"type": "string", "maxLength": 240}} }, "additionalProperties": false }, "GaugeCapacityResponse": { "type": "object", "required": ["object", "enabled", "data"], "properties": {"object": {"type": "string", "const": "msty.nexus.gauge_capacity"}, "enabled": {"type": "boolean"}, "data": {"type": "array", "maxItems": 256, "items": {"$ref": "#/components/schemas/GaugeCapacitySignal"}}}, "additionalProperties": false }, "GaugeDiagnostic": { "type": "object", "required": ["accountRef", "providerId", "adapterId", "authMode", "status", "credentialConfigured", "readingAvailable", "capabilityCount"], "properties": { "accountRef": {"type": "string", "maxLength": 169}, "providerId": {"type": "string", "maxLength": 160}, "adapterId": {"type": "string", "maxLength": 160}, "authMode": {"$ref": "#/components/schemas/GaugeAuthMode"}, "status": {"$ref": "#/components/schemas/GaugeSourceStatus"}, "problemCode": {"type": "string", "maxLength": 160}, "credentialConfigured": {"type": "boolean"}, "readingAvailable": {"type": "boolean"}, "readingAgeSeconds": {"type": "integer", "format": "int64", "minimum": 0}, "capabilityCount": {"type": "integer", "minimum": 0, "maximum": 32}, "lastAttemptAt": {"type": "string", "format": "date-time"}, "lastSuccessAt": {"type": "string", "format": "date-time"} }, "additionalProperties": false }, "GaugeDiagnosticsResponse": { "type": "object", "required": ["object", "enabled", "generatedAt", "data"], "properties": {"object": {"type": "string", "const": "msty.nexus.gauge_diagnostics"}, "enabled": {"type": "boolean"}, "generatedAt": {"type": "string", "format": "date-time"}, "data": {"type": "array", "maxItems": 256, "items": {"$ref": "#/components/schemas/GaugeDiagnostic"}}}, "additionalProperties": false }, "GaugeAuthSessionStatus": {"type": "string", "enum": ["pending", "complete", "expired", "cancelled", "failed"]}, "GaugeAuthSession": { "type": "object", "required": ["object", "id", "providerId", "authMode", "status", "expiresAt"], "properties": {"object": {"type": "string", "const": "msty.nexus.gauge_auth_session"}, "id": {"type": "string", "maxLength": 160}, "providerId": {"type": "string", "maxLength": 160}, "authMode": {"$ref": "#/components/schemas/GaugeAuthMode"}, "status": {"$ref": "#/components/schemas/GaugeAuthSessionStatus"}, "verificationUri": {"type": "string", "format": "uri", "maxLength": 2048}, "userCode": {"type": "string", "maxLength": 32}, "pollAfterSeconds": {"type": "integer", "format": "int64", "minimum": 1, "maximum": 300}, "expiresAt": {"type": "string", "format": "date-time"}, "accountId": {"type": "string", "maxLength": 160}, "problemCode": {"type": "string", "maxLength": 160}}, "additionalProperties": false }, "GaugeAuthSessionCreate": { "type": "object", "required": ["providerId", "authMode", "clientId"], "properties": {"providerId": {"type": "string", "minLength": 1, "maxLength": 160}, "authMode": {"$ref": "#/components/schemas/GaugeAuthMode"}, "label": {"type": "string", "maxLength": 160}, "clientId": {"type": "string", "minLength": 8, "maxLength": 160, "writeOnly": true}}, "additionalProperties": false }, "GaugeBudgetBasis": {"type": "string", "enum": ["actual", "estimated", "actual_plus_estimated"]}, "GaugeBudgetPeriod": {"type": "string", "enum": ["daily", "monthly"]}, "GaugeBudgetState": {"type": "string", "enum": ["under", "warning", "over", "no_data"]}, "GaugeProjectBudget": { "type": "object", "required": ["id", "project", "currency", "limit", "basis", "period", "warningPercent", "enabled", "createdAt", "updatedAt"], "properties": { "id": {"type": "string", "maxLength": 160}, "project": {"type": "string", "maxLength": 320}, "currency": {"type": "string", "const": "USD"}, "limit": {"type": "number", "exclusiveMinimum": 0}, "basis": {"$ref": "#/components/schemas/GaugeBudgetBasis"}, "period": {"$ref": "#/components/schemas/GaugeBudgetPeriod"}, "warningPercent": {"type": "number", "minimum": 1, "maximum": 100}, "enabled": {"type": "boolean"}, "createdAt": {"type": "string", "format": "date-time"}, "updatedAt": {"type": "string", "format": "date-time"} }, "additionalProperties": false }, "GaugeProjectBudgetStatus": { "type": "object", "required": ["budget", "periodStart", "periodEnd", "actualSpendUsd", "estimatedSpendUsd", "countedSpendUsd", "percent", "state", "hasActual", "hasEstimated"], "properties": { "budget": {"$ref": "#/components/schemas/GaugeProjectBudget"}, "periodStart": {"type": "string", "format": "date-time"}, "periodEnd": {"type": "string", "format": "date-time"}, "actualSpendUsd": {"type": "number", "minimum": 0}, "estimatedSpendUsd": {"type": "number", "minimum": 0}, "countedSpendUsd": {"type": "number", "minimum": 0}, "percent": {"type": "number", "minimum": 0}, "state": {"$ref": "#/components/schemas/GaugeBudgetState"}, "hasActual": {"type": "boolean"}, "hasEstimated": {"type": "boolean"} }, "additionalProperties": false }, "GaugeBudgetsResponse": { "type": "object", "required": ["object", "data"], "properties": {"object": {"type": "string", "const": "msty.nexus.gauge_budgets"}, "data": {"type": "array", "maxItems": 128, "items": {"$ref": "#/components/schemas/GaugeProjectBudgetStatus"}}}, "additionalProperties": false }, "GaugeBudgetCreate": { "type": "object", "required": ["project", "currency", "limit", "basis", "period", "warningPercent"], "properties": {"project": {"type": "string", "minLength": 1, "maxLength": 320}, "currency": {"type": "string", "const": "USD"}, "limit": {"type": "number", "exclusiveMinimum": 0}, "basis": {"$ref": "#/components/schemas/GaugeBudgetBasis"}, "period": {"$ref": "#/components/schemas/GaugeBudgetPeriod"}, "warningPercent": {"type": "number", "minimum": 1, "maximum": 100}, "enabled": {"type": "boolean"}}, "additionalProperties": false }, "GaugeBudgetUpdate": { "type": "object", "minProperties": 1, "properties": {"project": {"type": "string", "minLength": 1, "maxLength": 320}, "limit": {"type": "number", "exclusiveMinimum": 0}, "basis": {"$ref": "#/components/schemas/GaugeBudgetBasis"}, "period": {"$ref": "#/components/schemas/GaugeBudgetPeriod"}, "warningPercent": {"type": "number", "minimum": 1, "maximum": 100}, "enabled": {"type": "boolean"}}, "additionalProperties": false }, "GaugeBudgetDeleteResponse": {"type": "object", "required": ["deleted"], "properties": {"deleted": {"type": "boolean"}}, "additionalProperties": false}, "GaugeAlertScope": {"type": "string", "enum": ["global", "provider", "account", "window", "project"]}, "GaugeAlertTrigger": {"type": "string", "enum": ["quota_remaining", "forecast_risk", "reset", "credit_expiry", "spend", "incident", "authentication", "better_alternative"]}, "GaugeAlertEventState": {"type": "string", "enum": ["active", "resolved"]}, "GaugeAlertDeliveryState": {"type": "string", "enum": ["pending", "delivered", "suppressed", "failed"]}, "GaugeAlertRule": { "type": "object", "required": ["id", "scope", "trigger", "cooldownSeconds", "enabled", "createdAt", "updatedAt"], "properties": { "id": {"type": "string", "maxLength": 160}, "scope": {"$ref": "#/components/schemas/GaugeAlertScope"}, "scopeId": {"type": "string", "maxLength": 320}, "trigger": {"$ref": "#/components/schemas/GaugeAlertTrigger"}, "threshold": {"type": "number"}, "windowSeconds": {"type": "integer", "format": "int64", "minimum": 0, "maximum": 2592000}, "cooldownSeconds": {"type": "integer", "format": "int64", "minimum": 60, "maximum": 604800}, "enabled": {"type": "boolean"}, "createdAt": {"type": "string", "format": "date-time"}, "updatedAt": {"type": "string", "format": "date-time"} }, "additionalProperties": false }, "GaugeAlertRuleCreate": { "type": "object", "required": ["scope", "trigger"], "properties": { "scope": {"$ref": "#/components/schemas/GaugeAlertScope"}, "scopeId": {"type": "string", "maxLength": 320}, "trigger": {"$ref": "#/components/schemas/GaugeAlertTrigger"}, "threshold": {"type": "number"}, "windowSeconds": {"type": "integer", "format": "int64", "minimum": 0, "maximum": 2592000}, "cooldownSeconds": {"type": "integer", "format": "int64", "minimum": 0, "maximum": 604800}, "enabled": {"type": "boolean"} }, "additionalProperties": false }, "GaugeAlertRuleUpdate": { "type": "object", "minProperties": 1, "properties": { "scope": {"$ref": "#/components/schemas/GaugeAlertScope"}, "scopeId": {"type": "string", "maxLength": 320}, "trigger": {"$ref": "#/components/schemas/GaugeAlertTrigger"}, "threshold": {"type": "number"}, "clearThreshold": {"type": "boolean"}, "windowSeconds": {"type": "integer", "format": "int64", "minimum": 0, "maximum": 2592000}, "cooldownSeconds": {"type": "integer", "format": "int64", "minimum": 60, "maximum": 604800}, "enabled": {"type": "boolean"} }, "additionalProperties": false }, "GaugeAlertRulesResponse": { "type": "object", "required": ["object", "data"], "properties": { "object": {"type": "string", "const": "msty.nexus.gauge_alert_rules"}, "data": {"type": "array", "maxItems": 128, "items": {"$ref": "#/components/schemas/GaugeAlertRule"}} }, "additionalProperties": false }, "GaugeAlertEvent": { "type": "object", "required": ["id", "ruleId", "trigger", "scope", "state", "messageKey", "observedAt", "createdAt", "delivery"], "properties": { "id": {"type": "string", "maxLength": 160}, "ruleId": {"type": "string", "maxLength": 160}, "accountId": {"type": "string", "maxLength": 160}, "providerId": {"type": "string", "maxLength": 160}, "trigger": {"$ref": "#/components/schemas/GaugeAlertTrigger"}, "scope": {"$ref": "#/components/schemas/GaugeAlertScope"}, "scopeId": {"type": "string", "maxLength": 320}, "subjectId": {"type": "string", "maxLength": 320}, "state": {"$ref": "#/components/schemas/GaugeAlertEventState"}, "messageKey": {"type": "string", "maxLength": 240}, "value": {"type": "number"}, "threshold": {"type": "number"}, "observedAt": {"type": "string", "format": "date-time"}, "createdAt": {"type": "string", "format": "date-time"}, "delivery": {"$ref": "#/components/schemas/GaugeAlertDeliveryState"}, "deliveredAt": {"type": "string", "format": "date-time"} }, "additionalProperties": false }, "GaugeAlertEventsResponse": { "type": "object", "required": ["object", "data", "hasMore"], "properties": { "object": {"type": "string", "const": "msty.nexus.gauge_alert_events"}, "data": {"type": "array", "maxItems": 200, "items": {"$ref": "#/components/schemas/GaugeAlertEvent"}}, "hasMore": {"type": "boolean"}, "nextOffset": {"type": "integer", "minimum": 1, "maximum": 1000200} }, "additionalProperties": false }, "GaugeAlertDeleteResponse": { "type": "object", "required": ["deleted"], "properties": {"deleted": {"type": "boolean"}}, "additionalProperties": false }, "GaugeAlertDeliveryUpdate": { "type": "object", "required": ["delivery"], "properties": {"delivery": {"type": "string", "enum": ["delivered", "suppressed", "failed"]}}, "additionalProperties": false }, "GaugeAlertDeliveryResponse": { "type": "object", "required": ["updated"], "properties": {"updated": {"type": "boolean"}}, "additionalProperties": false }, "GaugeAction": { "type": "object", "description": "A safe registry-owned action. Arbitrary external URLs are never returned.", "required": ["id", "kind", "labelKey", "enabled"], "properties": { "id": {"type": "string", "maxLength": 160}, "kind": {"$ref": "#/components/schemas/GaugeActionKind"}, "labelKey": {"type": "string", "maxLength": 240}, "enabled": {"type": "boolean"} }, "additionalProperties": false }, "GaugeConfigField": { "type": "object", "required": ["id", "labelKey", "kind", "required", "secret"], "properties": { "id": {"type": "string"}, "labelKey": {"type": "string"}, "kind": {"$ref": "#/components/schemas/GaugeConfigFieldKind"}, "required": {"type": "boolean"}, "secret": {"type": "boolean"}, "placeholderKey": {"type": "string"}, "choices": {"type": "array", "items": {"type": "string"}} }, "additionalProperties": false }, "GaugeProviderDescriptor": { "type": "object", "required": ["id", "displayNameKey", "authModes", "capabilities", "configFields", "defaultEnabled"], "properties": { "id": {"type": "string"}, "displayNameKey": {"type": "string"}, "authModes": {"type": "array", "items": {"$ref": "#/components/schemas/GaugeAuthMode"}}, "capabilities": {"type": "array", "items": {"$ref": "#/components/schemas/GaugeCapability"}}, "configFields": {"type": "array", "items": {"$ref": "#/components/schemas/GaugeConfigField"}}, "defaultEnabled": {"type": "boolean"} }, "additionalProperties": false }, "GaugeAccountSummary": { "type": "object", "description": "A redacted Gauge account. Credential values and references are never included.", "required": ["id", "providerId", "label", "authMode", "enabled", "active", "credentialConfigured", "status", "capabilities"], "properties": { "id": {"type": "string"}, "providerId": {"type": "string"}, "label": {"type": "string"}, "identity": {"$ref": "#/components/schemas/GaugeIdentity"}, "plan": {"type": "string"}, "authMode": {"$ref": "#/components/schemas/GaugeAuthMode"}, "enabled": {"type": "boolean"}, "active": {"type": "boolean"}, "credentialConfigured": {"type": "boolean"}, "status": {"$ref": "#/components/schemas/GaugeSourceStatus"}, "capabilities": {"type": "array", "items": {"$ref": "#/components/schemas/GaugeCapability"}}, "problemCode": {"type": "string"}, "lastAttemptAt": {"type": "string", "format": "date-time"}, "lastSuccessAt": {"type": "string", "format": "date-time"} }, "additionalProperties": false }, "GaugeAccountCreate": { "type": "object", "description": "Creates a provider account. credential is write-only and never echoed.", "required": ["providerId", "authMode"], "properties": { "providerId": {"type": "string", "minLength": 1}, "label": {"type": "string", "maxLength": 160}, "authMode": {"$ref": "#/components/schemas/GaugeAuthMode"}, "enabled": {"type": "boolean"}, "credential": {"type": "string", "minLength": 1, "writeOnly": true}, "config": {"type": "object", "additionalProperties": {"type": "string"}} }, "additionalProperties": false }, "GaugeAccountUpdate": { "type": "object", "description": "Updates mutable account state. credential is write-only and never echoed.", "minProperties": 1, "properties": { "label": {"type": "string", "maxLength": 160}, "enabled": {"type": "boolean"}, "active": {"type": "boolean"}, "credential": {"type": "string", "minLength": 1, "writeOnly": true}, "clearCredential": {"type": "boolean"}, "config": {"type": "object", "additionalProperties": {"type": "string"}} }, "additionalProperties": false }, "GaugeAccountDeleteResponse": { "type": "object", "required": ["deleted"], "properties": {"deleted": {"type": "boolean"}}, "additionalProperties": false }, "GaugeSourceSummary": { "type": "object", "description": "Public Gauge source state. Credential material and credential references are never included.", "required": [ "id", "kind", "providerId", "authMode", "enabled", "credentialConfigured", "status", "capabilities" ], "properties": { "id": { "type": "string" }, "kind": { "$ref": "#/components/schemas/GaugeSourceKind" }, "providerId": { "type": "string" }, "accountLabel": { "type": "string" }, "authMode": { "$ref": "#/components/schemas/GaugeAuthMode" }, "enabled": { "type": "boolean" }, "credentialConfigured": { "type": "boolean" }, "status": { "$ref": "#/components/schemas/GaugeSourceStatus" }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/GaugeCapability" } }, "problemCode": { "type": "string", "description": "Stable redacted problem code suitable for client-owned copy." }, "lastAttemptAt": { "type": "string", "format": "date-time" }, "lastSuccessAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "GaugeWindow": { "type": "object", "description": "One provider limit window normalized to percentages from 0 through 100.", "required": [ "id", "usedPercent", "remainingPercent", "forecastState" ], "properties": { "id": { "type": "string" }, "label": { "type": "string", "maxLength": 160 }, "category": { "$ref": "#/components/schemas/GaugeQuotaCategory" }, "scope": { "type": "string", "maxLength": 160 }, "unit": { "type": "string", "maxLength": 32 }, "used": { "type": "number" }, "remaining": { "type": "number" }, "limit": { "type": "number" }, "usedPercent": { "type": "number", "minimum": 0, "maximum": 100 }, "remainingPercent": { "type": "number", "minimum": 0, "maximum": 100 }, "startsAt": { "type": "string", "format": "date-time" }, "resetsAt": { "type": "string", "format": "date-time" }, "resetKind": { "$ref": "#/components/schemas/GaugeResetKind" }, "windowSeconds": { "type": "integer", "format": "int64", "minimum": 0 }, "unlimited": { "type": "boolean" }, "unavailable": { "type": "boolean" }, "forecastState": { "$ref": "#/components/schemas/GaugeForecastState" }, "expectedUsedPercent": { "type": "number", "minimum": 0, "maximum": 100 }, "paceDeltaPercent": { "type": "number" }, "projectedExhaustedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "GaugeBalance": { "type": "object", "required": [ "unit" ], "properties": { "unit": { "type": "string" }, "available": { "type": "number" }, "limit": { "type": "number" }, "used": { "type": "number" } }, "additionalProperties": false }, "GaugeCost": { "type": "object", "description": "Provider-reconciled spend remains separate from locally estimated spend.", "required": [ "currency" ], "properties": { "currency": { "type": "string" }, "actual": { "type": "number" }, "estimated": { "type": "number" }, "periodStart": { "type": "string", "format": "date-time" }, "periodEnd": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "GaugeUsage": { "type": "object", "required": [ "requests", "inputTokens", "outputTokens", "totalTokens" ], "properties": { "requests": { "type": "integer", "format": "int64", "minimum": 0 }, "inputTokens": { "type": "integer", "format": "int64", "minimum": 0 }, "outputTokens": { "type": "integer", "format": "int64", "minimum": 0 }, "totalTokens": { "type": "integer", "format": "int64", "minimum": 0 } }, "additionalProperties": false }, "GaugeHealth": { "type": "object", "required": [ "state", "incidentCount" ], "properties": { "state": { "$ref": "#/components/schemas/GaugeHealthState" }, "incidentCount": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "GaugeDailyPoint": { "type": "object", "required": [ "day", "requests", "totalTokens" ], "properties": { "day": { "type": "string", "format": "date" }, "requests": { "type": "integer", "format": "int64", "minimum": 0 }, "totalTokens": { "type": "integer", "format": "int64", "minimum": 0 }, "actualCostUsd": { "type": "number" }, "estimatedCostUsd": { "type": "number" } }, "additionalProperties": false }, "GaugeMetricKind": { "type": "string", "enum": ["counter", "gauge", "rate", "amount", "duration"] }, "GaugeMetricPoint": { "type": "object", "required": ["at", "value"], "properties": { "at": {"type": "string", "format": "date-time"}, "value": {"type": "number"} }, "additionalProperties": false }, "GaugeMetric": { "type": "object", "required": ["id", "label", "kind", "unit", "value"], "properties": { "id": {"type": "string", "maxLength": 160}, "label": {"type": "string", "maxLength": 160}, "kind": {"$ref": "#/components/schemas/GaugeMetricKind"}, "unit": {"type": "string", "maxLength": 32}, "value": {"type": "number"}, "periodStart": {"type": "string", "format": "date-time"}, "periodEnd": {"type": "string", "format": "date-time"}, "series": { "type": "array", "maxItems": 366, "items": {"$ref": "#/components/schemas/GaugeMetricPoint"} } }, "additionalProperties": false }, "GaugeSnapshot": { "type": "object", "description": "Normalized, redacted output from one Gauge source.", "required": [ "id", "sourceId", "observedAt", "windows", "usage", "health", "daily" ], "properties": { "id": { "type": "string" }, "sourceId": { "type": "string" }, "accountId": { "type": "string" }, "observedAt": { "type": "string", "format": "date-time" }, "plan": { "type": "string" }, "identity": { "$ref": "#/components/schemas/GaugeIdentity" }, "windows": { "type": "array", "items": { "$ref": "#/components/schemas/GaugeWindow" } }, "balance": { "$ref": "#/components/schemas/GaugeBalance" }, "balances": { "type": "array", "maxItems": 16, "items": { "$ref": "#/components/schemas/GaugeBalance" } }, "credits": { "type": "array", "maxItems": 64, "items": { "$ref": "#/components/schemas/GaugeCredit" } }, "metrics": { "type": "array", "maxItems": 64, "items": { "$ref": "#/components/schemas/GaugeMetric" } }, "cost": { "$ref": "#/components/schemas/GaugeCost" }, "usage": { "$ref": "#/components/schemas/GaugeUsage" }, "health": { "$ref": "#/components/schemas/GaugeHealth" }, "providerStatus": { "$ref": "#/components/schemas/GaugeProviderStatus" }, "daily": { "type": "array", "items": { "$ref": "#/components/schemas/GaugeDailyPoint" } }, "attribution": { "type": "array", "maxItems": 4096, "items": { "$ref": "#/components/schemas/GaugeAttribution" } }, "provenance": { "type": "array", "maxItems": 64, "items": { "$ref": "#/components/schemas/GaugeProvenance" } }, "actions": { "type": "array", "maxItems": 32, "items": { "$ref": "#/components/schemas/GaugeAction" } } }, "additionalProperties": false }, "GaugeSourceView": { "type": "object", "required": [ "source" ], "properties": { "source": { "$ref": "#/components/schemas/GaugeSourceSummary" }, "snapshot": { "$ref": "#/components/schemas/GaugeSnapshot" } }, "additionalProperties": false }, "GaugeHistoryPoint": { "type": "object", "required": [ "sourceId", "observedAt" ], "properties": { "sourceId": { "type": "string" }, "observedAt": { "type": "string", "format": "date-time" }, "windowId": { "type": "string" }, "remainingPercent": { "type": "number", "minimum": 0, "maximum": 100 }, "actualCost": { "type": "number" }, "estimatedCost": { "type": "number" } }, "additionalProperties": false }, "GaugeDashboardSummary": { "type": "object", "required": [ "readySources", "attentionSources", "actualCostUsd", "estimatedCostUsd", "totalTokens" ], "properties": { "readySources": { "type": "integer", "minimum": 0 }, "attentionSources": { "type": "integer", "minimum": 0 }, "nextResetAt": { "type": "string", "format": "date-time" }, "actualCostUsd": { "type": "number" }, "estimatedCostUsd": { "type": "number" }, "totalTokens": { "type": "integer", "format": "int64", "minimum": 0, "description": "Tokens recorded by the local Nexus meter. External reports are not added because they may overlap." } }, "additionalProperties": false }, "GaugeDashboard": { "type": "object", "required": [ "object", "enabled", "generatedAt", "summary", "sources", "history", "historyTruncated" ], "properties": { "object": { "type": "string", "const": "msty.nexus.gauge" }, "enabled": { "type": "boolean" }, "generatedAt": { "type": "string", "format": "date-time" }, "summary": { "$ref": "#/components/schemas/GaugeDashboardSummary" }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/GaugeSourceView" } }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/GaugeHistoryPoint" } }, "historyTruncated": { "type": "boolean", "description": "True when the requested history exceeded the bounded response and only the most recent points are returned." } }, "additionalProperties": false }, "GaugeSourcesResponse": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string", "const": "msty.nexus.gauge_sources" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/GaugeSourceSummary" } } }, "additionalProperties": false }, "GaugeProvidersResponse": { "type": "object", "required": ["object", "data"], "properties": { "object": { "type": "string", "const": "msty.nexus.gauge_providers" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/GaugeProviderDescriptor" } } }, "additionalProperties": false }, "GaugeAccountsResponse": { "type": "object", "required": ["object", "data"], "properties": { "object": { "type": "string", "const": "msty.nexus.gauge_accounts" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/GaugeAccountSummary" } } }, "additionalProperties": false }, "GaugeSourceUpdate": { "type": "object", "description": "Write-only Gauge source setup. At least one field is required. credential is never echoed by any response.", "minProperties": 1, "properties": { "enabled": { "type": "boolean" }, "credential": { "type": "string", "minLength": 1, "writeOnly": true }, "clearCredential": { "type": "boolean" }, "config": { "type": "object", "description": "Allow-listed non-secret source configuration such as an OpenAI project ID.", "additionalProperties": { "type": "string" } } }, "additionalProperties": false }, "GaugeRefreshRequest": { "type": "object", "properties": { "sourceIds": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "GaugeRefreshOutcome": { "type": "object", "required": [ "sourceId", "status" ], "properties": { "sourceId": { "type": "string" }, "status": { "$ref": "#/components/schemas/GaugeSourceStatus" }, "problemCode": { "type": "string" } }, "additionalProperties": false }, "GaugeRefreshResponse": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string", "const": "msty.nexus.gauge_refresh" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/GaugeRefreshOutcome" } } }, "additionalProperties": false }, "GaugeDeleteHistoryResponse": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "AccountProvider": { "type": "string", "description": "Subscription account provider connectable through a runtime account surface.", "enum": [ "claude", "gemini", "codex" ] }, "ServiceAccount": { "type": "object", "description": "Redacted connected-account record. The ID is the stored credential file name inside the Nexus-owned runtime data directory; token material, refresh tokens, and local filesystem paths are never returned.", "required": [ "object", "serviceId", "id", "provider" ], "properties": { "object": { "type": "string", "enum": [ "msty.nexus.service_account" ] }, "serviceId": { "type": "string" }, "id": { "type": "string" }, "provider": { "type": "string", "description": "Best-effort provider classification for display. Values usually match AccountProvider but may fall back to an upstream type string." }, "label": { "type": "string", "description": "Optional display label such as the signed-in account email when the runtime reports one." } }, "additionalProperties": false }, "ServiceAccountList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceAccount" } } }, "additionalProperties": false }, "ServiceAccountLoginRequest": { "type": "object", "required": [ "provider" ], "properties": { "provider": { "$ref": "#/components/schemas/AccountProvider" } }, "additionalProperties": false }, "ServiceAccountLogin": { "type": "object", "description": "State of one account sign-in flow. The url is the upstream provider authorization endpoint for the user to open in a browser; Nexus never returns the runtime management secret, stored credential contents, or callback tokens.", "required": [ "object", "serviceId", "loginId", "status" ], "properties": { "object": { "type": "string", "enum": [ "msty.nexus.service_account_login" ] }, "serviceId": { "type": "string" }, "loginId": { "type": "string", "description": "Opaque poll handle for this sign-in flow." }, "provider": { "$ref": "#/components/schemas/AccountProvider" }, "url": { "type": "string", "description": "Provider authorization URL the user must open to complete sign-in. Present on flow start." }, "status": { "type": "string", "enum": [ "pending", "ok", "error" ] }, "error": { "type": "string", "description": "Stable upstream failure text when status is error." }, "syncJobId": { "type": "string", "description": "Model sync job queued automatically after the first successful completion poll." } }, "additionalProperties": false }, "PresetAccelerationAction": { "type": "string", "enum": [ "validate", "apply", "disable" ] }, "PresetAccelerationWarning": { "type": "object", "required": [ "code", "messageKey" ], "properties": { "code": { "type": "string" }, "messageKey": { "type": "string" }, "field": { "type": "string" } }, "additionalProperties": false }, "PresetAccelerationStats": { "type": "object", "properties": { "draftAcceptedTokens": { "type": "integer", "format": "int64" }, "draftTotalTokens": { "type": "integer", "format": "int64" }, "acceptanceRate": { "type": "number", "format": "double" } }, "additionalProperties": false }, "PresetAccelerationProfile": { "type": "object", "required": [ "targetModelId", "enabled", "mode", "compatibilityStatus", "reloadRequirement" ], "properties": { "presetSlug": { "type": "string" }, "targetModelId": { "type": "string" }, "runtimeId": { "type": "string" }, "enabled": { "type": "boolean" }, "mode": { "$ref": "#/components/schemas/AccelerationMode" }, "draftModelId": { "type": "string" }, "compatibilityStatus": { "$ref": "#/components/schemas/AccelerationCompatibilityStatus" }, "reloadRequirement": { "$ref": "#/components/schemas/AccelerationReloadRequirement" }, "reasonCode": { "type": "string", "description": "Stable machine-readable status reason. Values are safe for UI branching and do not include paths or raw runtime errors." }, "messageKey": { "type": "string", "description": "Localization key for client-owned copy. Setup surfaces should prefer speed/helper language over implementation terms." }, "supportedModes": { "type": "array", "items": { "$ref": "#/components/schemas/AccelerationMode" } }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/PresetAccelerationWarning" } }, "lastValidatedAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "runtimeConfigUpdatedAt": { "type": "string", "format": "date-time", "description": "Last time the runtime-facing acceleration configuration changed. Clients use reloadRequirement for UI decisions." }, "stats": { "$ref": "#/components/schemas/PresetAccelerationStats" } }, "additionalProperties": false }, "PresetAccelerationInput": { "type": "object", "required": [ "enabled", "mode" ], "properties": { "enabled": { "type": "boolean" }, "mode": { "$ref": "#/components/schemas/AccelerationMode" }, "draftModelId": { "type": "string", "description": "Nexus model ID for the helper model. Arbitrary per-request helper models and local paths are not accepted." } }, "additionalProperties": false }, "PresetAccelerationActionInput": { "type": "object", "required": [ "action" ], "properties": { "action": { "$ref": "#/components/schemas/PresetAccelerationAction" } }, "additionalProperties": false }, "PresetAccelerationValidationResult": { "type": "object", "required": [ "valid", "profile" ], "properties": { "valid": { "type": "boolean" }, "profile": { "$ref": "#/components/schemas/PresetAccelerationProfile" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/PresetAccelerationWarning" } }, "messageKey": { "type": "string" } }, "additionalProperties": false }, "PresetAccelerationActionResult": { "type": "object", "required": [ "action", "accepted", "profile" ], "properties": { "action": { "$ref": "#/components/schemas/PresetAccelerationAction" }, "accepted": { "type": "boolean" }, "profile": { "$ref": "#/components/schemas/PresetAccelerationProfile" }, "validation": { "$ref": "#/components/schemas/PresetAccelerationValidationResult" }, "job": { "$ref": "#/components/schemas/Job" }, "messageKey": { "type": "string" } }, "additionalProperties": false }, "FitRequest": { "type": "object", "required": [ "architecture", "nLayers", "context" ], "description": "Architecture dimensions for the memory-fit estimator, pre-resolved by the caller from GGUF or MLX metadata. architecture is the model_type (llama, qwen2, deepseek2, deepseek_v3, gemma3_text, ...). nKVHeads, headDim, hiddenSize, kvLoraRank, qkRopeHeadDim, slidingWindow are optional and follow the same fallback rules as llama.cpp / mlx-lm. Either fileBytes (GGUF or MLX bundle size) or numParams+bits+groupSize (quantized MLX) sizes the weights.", "properties": { "architecture": { "type": "string" }, "nLayers": { "type": "integer" }, "nHeads": { "type": "integer" }, "nKVHeads": { "type": "integer" }, "headDim": { "type": "integer" }, "hiddenSize": { "type": "integer" }, "kvLoraRank": { "type": "integer" }, "qkRopeHeadDim": { "type": "integer" }, "slidingWindow": { "type": "integer" }, "fileBytes": { "type": "integer" }, "numParams": { "type": "integer" }, "bits": { "type": "integer" }, "groupSize": { "type": "integer" }, "context": { "type": "integer" }, "runtime": { "type": "string", "enum": [ "ollama", "llamacpp", "mlx" ] }, "kvQuant": { "type": "string", "enum": [ "f16", "q8_0", "q4_0" ] }, "concurrent": { "type": "integer" } }, "additionalProperties": false }, "FitResult": { "type": "object", "required": [ "verdict", "breakdown", "availableBytes", "ceilingSource" ], "description": "Memory-fit estimate. verdict is fits (<75% of ceiling), tight (75-90%), wont_fit (>90%), or unknown (weights or architecture dims missing). breakdown.parts is itemised with weights/kv_cache/overhead; overhead is always tagged isEstimate. suggestions proposes a context length that would fit.", "properties": { "verdict": { "type": "string", "enum": [ "fits", "tight", "wont_fit", "unknown" ] }, "breakdown": { "$ref": "#/components/schemas/FitBreakdown" }, "availableBytes": { "type": "integer" }, "ceilingSource": { "type": "string" }, "suggestions": { "type": "array", "items": { "$ref": "#/components/schemas/FitSuggestion" } } }, "additionalProperties": false }, "FitBreakdown": { "type": "object", "required": [ "weightBytes", "kvBytes", "overheadBytes", "totalBytes", "parts" ], "properties": { "weightBytes": { "type": "integer" }, "kvBytes": { "type": "integer" }, "overheadBytes": { "type": "integer" }, "totalBytes": { "type": "integer" }, "parts": { "type": "array", "items": { "$ref": "#/components/schemas/FitPart" } }, "mla": { "type": "boolean" }, "uncertain": { "type": "boolean", "description": "True when required weight or KV dimensions were missing and totalBytes is a lower-bound estimate." } }, "additionalProperties": false }, "FitPart": { "type": "object", "required": [ "label", "bytes" ], "properties": { "label": { "type": "string" }, "bytes": { "type": "integer" }, "isEstimate": { "type": "boolean" } }, "additionalProperties": false }, "FitSuggestion": { "type": "object", "required": [ "label", "delta" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable suggestion action, such as lower_context." }, "label": { "type": "string", "description": "Compatibility display label for clients that do not localize suggestion codes." }, "context": { "type": "integer", "description": "Target context length in tokens when code is lower_context." }, "delta": { "type": "integer", "description": "Bytes saved (negative)." } }, "additionalProperties": false }, "FitCandidateRequest": { "type": "object", "required": [ "repo", "file", "kind", "context" ], "description": "Identifies a Hugging Face model to lazily probe for architecture dims. revision defaults to main. kind is gguf or mlx.", "properties": { "repo": { "type": "string" }, "revision": { "type": "string" }, "file": { "type": "string" }, "kind": { "type": "string", "enum": [ "gguf", "mlx" ] }, "fileBytes": { "type": "integer" }, "context": { "type": "integer" }, "runtime": { "type": "string", "enum": [ "ollama", "llamacpp", "mlx" ] }, "kvQuant": { "type": "string", "enum": [ "f16", "q8_0", "q4_0" ] } }, "additionalProperties": false }, "FitCandidateResult": { "type": "object", "required": [ "verdict", "breakdown", "availableBytes", "ceilingSource" ], "description": "Memory-fit estimate for a remote candidate. When extraction fails, verdict is unknown and error explains why; breakdown reports the known weights and estimated overhead as a lower-bound estimate when fileBytes was supplied.", "properties": { "verdict": { "type": "string", "enum": [ "fits", "tight", "wont_fit", "unknown" ] }, "breakdown": { "$ref": "#/components/schemas/FitBreakdown" }, "availableBytes": { "type": "integer" }, "ceilingSource": { "type": "string" }, "suggestions": { "type": "array", "items": { "$ref": "#/components/schemas/FitSuggestion" } }, "error": { "type": "string" } }, "additionalProperties": false } } } }