API and SDKs

Msty Nexus is API-first. The app, CLI, SDKs, smoke clients, and browser console all exercise the same local Runtime API.

Use the OpenAPI contract for the machine-readable surface.

API contract

Public process endpoints:

• GET /health
• GET /version

Authenticated API families include:

• Gateway routes
• Settings and capabilities
• Providers
• Models
• Model actions
• Loaded models
• Model library health
• Model placement and benchmarks
• Presets
• Preset validation and acceleration actions
• Route packs and Smart Route
• Runtime discovery
• Services and service accounts
• Jobs and job events
• Local tokens and pairing
• Usage metrics
• Gauge
• Audit events
• Hardware telemetry

Every /v1/* request requires a local Nexus token except loopback-only pairing request creation.

Capabilities discovery

Call GET /v1/capabilities before rendering controls or assuming feature support.

Capabilities include:

• Endpoint families and operation-level routes
• Provider kinds
• Per-provider-kind endpoint/action support
• Global provider, service, and model action vocabularies
• Registry sources
• Supported scopes
• Preset parameter capabilities
• Feature surface flags

Use protocol IDs from capabilities for behavior and localize display labels in the client.

Current endpoint-family IDs include openai.chat_completions, openai.embeddings, openai.responses, openai.images, openai.audio_speech, openai.audio_transcriptions, anthropic.messages, and rerank.documents.

Go SDK

The Go SDK lives in pkg/nexusclient in the Nexus source repo.

Use it for:

• Health/version reads
• Settings/capability reads
• Provider/model/preset/service CRUD
• Job polling and SSE events
• Gateway calls
• Usage and Gauge calls
• Smoke-test clients

Example shape:

client := nexusclient.New("http://127.0.0.1:3939", "local-nexus-token")
models, err := client.ListModels(ctx)
if err != nil {
    return err
}
_ = models

The SDK keeps local Nexus authentication separate from provider credentials.

TypeScript SDK

The TypeScript SDK lives in sdk/typescript in the Nexus source repo.

Example:

import { NexusClient } from "@msty-ai/nexus";

const nexus = new NexusClient({
  baseUrl: "http://127.0.0.1:3939",
  token: localNexusToken,
});

const version = await nexus.version();
const models = await nexus.listModels();
const response = await nexus.responses({
  model: "@preset/coder-fast",
  input: "Summarize the current status.",
});

Gateway methods with WithResponse return provider-shaped payloads plus the best request ID from response headers. Streaming variants return the request ID after the stream completes.

Gateway methods with WithOptions accept safe provider hint headers. Protected headers such as local Nexus auth, content type, cookies, proxy auth, and hop-by-hop transport headers remain SDK-owned.

SDKs also expose preset validation, loaded-model reads, model-library health, Gauge endpoints, image/audio/rerank gateway routes, and typed warning payloads where supported by the current source branch.

CLI and smoke clients

The source repo includes:

• msty-nexus: Runtime server
• msty-nexusctl: CLI client for local management and diagnostics
• msty-nexus-smoke: repeatable contract and live smoke validation
• msty-nexus-workbench: app-shaped dogfood client over the Go SDK

The smoke client validates public contracts without printing credentials, raw model output, local paths, request IDs, or provider response bodies.

Browser console

The static browser console in examples/browser-console is a first-party browser harness for the local API. It keeps the local Nexus token in memory only and requires CORS to be configured before browser calls succeed.

The console can read redacted process, settings, capabilities, catalog, services, jobs, and audit summaries. It can also run explicit provider checks, model searches, gateway probes, service actions, model actions, and controlled catalog writes without accepting upstream provider keys.

Error handling

Errors use stable codes and a compatible envelope:

{
  "type": "error",
  "request_id": "nxs_req_example",
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request.",
    "type": "invalid_request_error",
    "param": null,
    "messageKey": "error.invalid.request",
    "details": {}
  }
}

Clients should branch on error.code and treat messageKey as the localization key.

Request IDs

Nexus sets:

• X-Msty-Nexus-Request-Id
• X-Request-Id
• request-id

Use these identifiers for local support correlation. Do not treat request IDs as credentials or authorization material.