Gateway

The Nexus gateway gives local clients one API surface for local and online models. Clients authenticate to Nexus with a local Nexus token; Nexus resolves the model, reads provider credentials from secure storage when needed, and forwards only safe provider hints upstream.

Base URL and authentication

Copy the gateway URL from the app. The default production listener is local-only:

http://127.0.0.1:3939

Accepted token forms:

Authorization: Bearer <local-nexus-token>
X-Msty-Nexus-Token: <local-nexus-token>
x-api-key: <local-nexus-token>

Use x-api-key for Anthropic-compatible clients that expect that header. It is still a local Nexus token and is never forwarded to the upstream provider.

Supported gateway routes

Nexus routes requests by model and endpoint family.

OpenAI-compatible routes include:

• GET /v1/models
• POST /v1/chat/completions
• POST /v1/embeddings
• POST /v1/responses
• POST /v1/responses/input_tokens
• POST /v1/responses/compact
• GET /v1/responses/{id}
• DELETE /v1/responses/{id}
• GET /v1/responses/{id}/input_items
• POST /v1/responses/{id}/cancel
• POST /v1/images/generations
• POST /v1/images/edits
• POST /v1/audio/speech
• POST /v1/audio/transcriptions

Anthropic-compatible routes include:

• POST /v1/messages
• POST /v1/messages/count_tokens

Rerank routes include:

• POST /v1/rerank

Not every provider or model supports every route. Check API and SDKs or GET /v1/capabilities for the current machine-readable contract.

Endpoint families

Model records advertise endpoint-family IDs:

• openai.chat_completions
• openai.embeddings
• openai.responses
• openai.images
• openai.audio_speech
• openai.audio_transcriptions
• anthropic.messages
• rerank.documents

Nexus validates the family before provider credential lookup. If a model lacks the required family, the request fails locally instead of reaching the provider.

Model values

Gateway requests can target:

• Direct model IDs such as openai/gpt-test, ollama/llama3.1:8b, or llamacpp/qwen.gguf
• Aliases such as default-chat
• Presets such as @preset/coder-fast
• Route packs such as @route/research

Direct model IDs take precedence over aliases. Hidden models are omitted from /v1/models and cannot be routed by direct ID or alias.

Multipart routes, including image edits and audio transcriptions, accept model IDs or aliases only. They do not accept presets or route packs because Nexus must resolve the multipart model field before streaming the upload onward.

Provider resolution

Nexus resolves requests in this order:

1. Identify the model, alias, preset, or route pack.
2. Validate the selected endpoint family.
3. Resolve the provider record and provider kind.
4. Merge preset defaults when a preset is used.
5. Apply request fields last.
6. Send the upstream request with the credential stored inside Runtime.

Preset params and provider-specific options act as defaults. A request body can override those values for one call.

Header boundary

Clients must not send upstream provider credentials to Nexus. Nexus ignores or blocks protected transport headers and sets provider authentication itself.

Allowed provider hints include non-secret headers for use cases like:

• OpenAI project or organization selection
• Anthropic beta feature headers
• OpenRouter referer, title, category, or experimental metadata

Nexus strips hop-by-hop headers, credential-bearing response headers, and provider CORS headers before responses reach clients.

Image, audio, and rerank behavior

Newer gateway routes follow the same local-token and model-family rules as text routes:

• Image generation uses JSON, can be routed by model, alias, preset, or route pack, and records provider-reported token counters when the provider returns them.
• Image edits use multipart/form-data, require one model field plus prompt and image or image[] file parts, and are direct-model-or-alias only.
• Speech accepts JSON text-to-speech requests and relays the provider's binary audio response byte-for-byte.
• Transcriptions accept multipart audio uploads or JSON input_audio, depending on provider support, and are direct-model-or-alias only for multipart requests.
• Rerank uses a vendor-neutral { model, query, documents[] } shape and returns indexed relevance scores.

Audio speech, audio transcription, image edit, and rerank requests are not token-metered in Usage today. Image generation records token counters only when the provider reports them.

Request IDs and errors

Every response includes a Nexus request ID:

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

Errors use stable machine-readable codes:

{
  "type": "error",
  "request_id": "nxs_req_example",
  "error": {
    "code": "MODEL_ENDPOINT_NOT_SUPPORTED",
    "message": "Model does not support this endpoint.",
    "type": "invalid_request_error",
    "param": "model",
    "messageKey": "error.model.endpoint.not.supported",
    "details": {}
  }
}

Branch on error.code, not on English message.

Browser clients and CORS

CORS is disabled by default. Add explicit browser origins in Settings > Network Access before calling Nexus from a browser page.

Important boundaries:

• Preflight requests for allowed origins do not need a token.
• Actual /v1/* requests always need a token.
• * is development-only and must be the only CORS entry when used.
• CORS does not change the bind address.

If a browser client fails before it reaches the API, check the CORS allow-list first. If a request reaches the API and returns UNAUTHORIZED, check the local Nexus token.