vikas8520-coder/nerve/nerve-inference

---\nname: nerve-inference\ndescription: "The core OpenAI-compatible inference endpoints: chat completions, embeddings, images, audio (TTS/STT), moderations, rerank, and the Responses API. The primary integration surface for AI agents."\n--- <!-- generated by src/lib/agentSkills/generator.ts; manual edits will be overwritten -->

Overview

The core OpenAI-compatible inference endpoints: chat completions, embeddings, images, audio (TTS/STT), moderations, rerank, and the Responses API. The primary integration surface for AI agents.

Authentication

All requests require a valid Bearer token or session cookie. Obtain a token via POST /api/auth/login or configure REQUIRE_API_KEY=false for local development.

Endpoints

POST /api/v1/chat/completions

Create chat completion

OpenAI-compatible chat completions endpoint. Routes to configured providers.

curl -X POST https://localhost:20128/api/v1/chat/completions \
  -H "Authorization: Bearer $NERVE_TOKEN"
  -H "Content-Type: application/json" \
  -d '{}'

GET /api/v1/ws

Chat completion over WebSocket (handshake + upgrade)

OpenAI-compatible chat over a WebSocket connection. GET with ?handshake=1 returns the connection descriptor (auth path, message protocol and live-event channels) as JSON; a plain GET without an Upgrade returns 426 Upgrade Required. After upgrading, the client exchanges JSON frames — {type:"request", id, payload:{model, messages}} to start a completion and {type:"cancel", id} to abort it. A separate live channel (default port LIVE_WS_PORT=20129, path /live) streams dashboard events on the requests, combo and credentials topics with a 15s heartbeat. Requires an API key.

curl https://localhost:20128/api/v1/ws \
  -H "Authorization: Bearer $NERVE_TOKEN"

POST /api/v1/providers/{provider}/chat/completions

Create chat completion (provider-specific)

Routes to a specific provider by name.

curl -X POST https://localhost:20128/api/v1/providers/{provider}/chat/completions \
  -H "Authorization: Bearer $NERVE_TOKEN"
  -H "Content-Type: application/json" \
  -d '{}'

POST /api/v1/api/chat

Ollama-compatible chat endpoint

Provides compatibility with Ollama's /api/chat format.

curl -X POST https://localhost:20128/api/v1/api/chat \
  -H "Authorization: Bearer $NERVE_TOKEN"
  -H "Content-Type: application/json" \
  -d '{}'

POST /api/v1/messages

Create message (Anthropic-compatible)

Anthropic Messages API endpoint. Routes to Claude providers.

curl -X POST https://localhost:20128/api/v1/messages \
  -H "Authorization: Bearer $NERVE_TOKEN"
  -H "Content-Type: application/json" \
  -d '{}'

POST /api/v1/messages/count_tokens

Count tokens for a message

curl -X POST https://localhost:20128/api/v1/messages/count_tokens \
  -H "Authorization: Bearer $NERVE_TOKEN"
  -H "Content-Type: application/json" \
  -d '{}'

POST /api/v1/responses

Create response (OpenAI Responses API)

OpenAI Responses API endpoint.

curl -X POST https://localhost:20128/api/v1/responses \
  -H "Authorization: Bearer $NERVE_TOKEN"
  -H "Content-Type: application/json" \
  -d '{}'

POST /api/v1/embeddings

Create embeddings

curl -X POST https://localhost:20128/api/v1/embeddings \
  -H "Authorization: Bearer $NERVE_TOKEN"
  -H "Content-Type: application/json" \
  -d '{}'

POST /api/v1/providers/{provider}/embeddings

Create embeddings (provider-specific)

curl -X POST https://localhost:20128/api/v1/providers/{provider}/embeddings \
  -H "Authorization: Bearer $NERVE_TOKEN"
  -H "Content-Type: application/json" \
  -d '{}'

POST /api/v1/images/generations

Generate images

curl -X POST https://localhost:20128/api/v1/images/generations \
  -H "Authorization: Bearer $NERVE_TOKEN"
  -H "Content-Type: application/json" \
  -d '{}'

POST /api/v1/providers/{provider}/images/generations

Generate images (provider-specific)

curl -X POST https://localhost:20128/api/v1/providers/{provider}/images/generations \
  -H "Authorization: Bearer $NERVE_TOKEN"
  -H "Content-Type: application/json" \
  -d '{}'

POST /api/v1/audio/speech

Generate speech audio

Text-to-speech endpoint. Routes to configured TTS providers.

curl -X POST https://localhost:20128/api/v1/audio/speech \
  -H "Authorization: Bearer $NERVE_TOKEN"
  -H "Content-Type: application/json" \
  -d '{}'

POST /api/v1/audio/transcriptions

Transcribe audio

Audio-to-text transcription endpoint.

curl -X POST https://localhost:20128/api/v1/audio/transcriptions \
  -H "Authorization: Bearer $NERVE_TOKEN"
  -H "Content-Type: application/json" \
  -d '{}'

POST /api/v1/moderations

Create moderation

Content moderation endpoint. Routes to configured moderation providers.

curl -X POST https://localhost:20128/api/v1/moderations \
  -H "Authorization: Bearer $NERVE_TOKEN"
  -H "Content-Type: application/json" \
  -d '{}'

POST /api/v1/rerank

Rerank documents

Document reranking endpoint.

curl -X POST https://localhost:20128/api/v1/rerank \
  -H "Authorization: Bearer $NERVE_TOKEN"
  -H "Content-Type: application/json" \
  -d '{}'

GET /api/v1

API v1 root endpoint

Returns basic API info and status.

curl https://localhost:20128/api/v1 \
  -H "Authorization: Bearer $NERVE_TOKEN"

GET /api/v1/providers/{provider}/models

List models for a specific provider

Returns only models for the selected provider with provider prefix removed from each model id.

curl https://localhost:20128/api/v1/providers/{provider}/models \
  -H "Authorization: Bearer $NERVE_TOKEN"

GET /api/v1/management/proxy-subscriptions

List proxy subscriptions

Lists all operator-supplied proxy subscription links. Also starts the background auto-refresh scheduler (idempotent) so enabled subscriptions stay in sync. Credentials embedded in url are redacted in the response.

curl https://localhost:20128/api/v1/management/proxy-subscriptions \
  -H "Authorization: Bearer $NERVE_TOKEN"

POST /api/v1/management/proxy-subscriptions

Create a proxy subscription

Creates a subscription record. If mode is rule, at least one entry in ruleProviders is required. updateIntervalMinutes defaults to 60 and enabled defaults to false when omitted or not exactly true.

curl -X POST https://localhost:20128/api/v1/management/proxy-subscriptions \
  -H "Authorization: Bearer $NERVE_TOKEN"
  -H "Content-Type: application/json" \
  -d '{}'

GET /api/v1/management/proxy-subscriptions/{id}

Get a proxy subscription

curl https://localhost:20128/api/v1/management/proxy-subscriptions/{id} \
  -H "Authorization: Bearer $NERVE_TOKEN"

PATCH /api/v1/management/proxy-subscriptions/{id}

Update a proxy subscription

Partial update — only fields present in the body are changed (name/url/mode/ruleProviders/localCoreEndpoint/updateIntervalMinutes/enabled).

curl -X PATCH https://localhost:20128/api/v1/management/proxy-subscriptions/{id} \
  -H "Authorization: Bearer $NERVE_TOKEN"
  -H "Content-Type: application/json" \
  -d '{}'

DELETE /api/v1/management/proxy-subscriptions/{id}

Delete a proxy subscription

Removes the subscription record and unbinds/drops its synced proxy_registry rows.

curl -X DELETE https://localhost:20128/api/v1/management/proxy-subscriptions/{id} \
  -H "Authorization: Bearer $NERVE_TOKEN"

GET /api/v1/management/proxy-subscriptions/{id}/nodes

Get a subscription's last-parsed node summary

Returns the last-parsed node list without re-fetching the (possibly slow) subscription URL.

curl https://localhost:20128/api/v1/management/proxy-subscriptions/{id}/nodes \
  -H "Authorization: Bearer $NERVE_TOKEN"

POST /api/v1/management/proxy-subscriptions/{id}/refresh

Refresh a proxy subscription

Re-fetches and re-parses the subscription URL, syncs its nodes into proxy_registry, and (re)binds the pool.

curl -X POST https://localhost:20128/api/v1/management/proxy-subscriptions/{id}/refresh \
  -H "Authorization: Bearer $NERVE_TOKEN"
  -H "Content-Type: application/json" \
  -d '{}'

POST /api/v1/ocr

Document OCR

Mistral OCR–compatible document OCR endpoint. Accepts a JSON body referencing a document/image and returns extracted text. Success responses carry the X-Nerve-* cost-telemetry headers.

curl -X POST https://localhost:20128/api/v1/ocr \
  -H "Authorization: Bearer $NERVE_TOKEN"
  -H "Content-Type: application/json" \
  -d '{}'

POST /api/v1/audio/translations

Translate audio to English

OpenAI Whisper–compatible audio translation (multipart/form-data). Unlike /api/v1/audio/transcriptions, output is always English regardless of the source language. Success responses carry the X-Nerve-* cost-telemetry headers.

curl -X POST https://localhost:20128/api/v1/audio/translations \
  -H "Authorization: Bearer $NERVE_TOKEN"
  -H "Content-Type: application/json" \
  -d '{}'

GET /api/v1/providers/suggested-models

Suggested media models

Read-only server-side proxy to the public HuggingFace Hub models search API, used by the dashboard to suggest models for a media provider kind without exposing an HF token client-side. Never accepts or returns credentials.

curl https://localhost:20128/api/v1/providers/suggested-models \
  -H "Authorization: Bearer $NERVE_TOKEN"

GET /api/v1/provider-plugin-manifest

Provider plugin manifest

Returns the manifest describing installed provider plugins.

curl https://localhost:20128/api/v1/provider-plugin-manifest \
  -H "Authorization: Bearer $NERVE_TOKEN"

Payloads

See the full OpenAPI specification at GET /api/openapi/spec or docs/openapi.yaml for detailed request/response schemas.

<!-- skill:custom-start --> <!-- Aggregated from: nerve-chat, nerve-image, nerve-tts, nerve-stt, nerve-embeddings, nerve-web-search, nerve-web-fetch -->

Chat completions

Requires NERVE_URL and NERVE_KEY. See entry-point SKILL for setup.

Endpoints

• POST $NERVE_URL/v1/chat/completions — OpenAI format
• POST $NERVE_URL/v1/messages — Anthropic Messages format
• POST $NERVE_URL/v1/responses — OpenAI Responses API

Discover

curl $NERVE_URL/v1/models | jq '.data[].id'

Combos (e.g. auto, cost-optimized, subscription) auto-fallback through multiple providers.

OpenAI format example

curl -X POST $NERVE_URL/v1/chat/completions \
  -H "Authorization: Bearer $NERVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-7",
    "messages": [{"role": "user", "content": "Refactor this function"}],
    "stream": true
  }'

Anthropic format example

curl -X POST $NERVE_URL/v1/messages \
  -H "Authorization: Bearer $NERVE_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-7",
    "max_tokens": 4096,
    "messages": [{"role": "user", "content": "Hi"}]
  }'

Tool use

Supports OpenAI tools array and Anthropic tools block. Tool results auto-compressed via RTK (47 filters: git-diff, grep, test-jest, terraform-plan, docker-logs, etc.) — 20-40% token savings. Disable per-request with X-Nerve-Rtk: off header.

Reasoning / thinking

Anthropic extended thinking and OpenAI Responses reasoning blocks are forwarded verbatim. Cached automatically via reasoning cache.

Errors

• 401 → invalid API key
• 400 invalid_model → model not in registry; check /v1/models
• 503 circuit_open → provider circuit breaker tripped; retry later or use combo
• 429 rate_limited → honor Retry-After; consider using a combo for auto-fallback

Image generation