API Overview - NeuralCleave

The NeuralCleave gateway exposes a REST API at http://localhost:7432/api/v1. All endpoints accept and return JSON.

Base URL

http://localhost:7432/api/v1

Change the host and port in [gateway] config if you’ve customized them.

Authentication

The API has no built-in authentication layer. When self-hosted on a local machine, the gateway is only accessible from localhost by default. If you expose the gateway publicly (behind nginx or a VPN), add authentication at the proxy level.

Response format

Success

{
  "field": "value"
}

Error

{
  "detail": "Human-readable error message"
}

HTTP status codes follow standard conventions: 200 for success, 201 for created, 404 for not found, 422 for validation errors.

WebSocket

The gateway also exposes a WebSocket at:

ws://localhost:7432/ws

The dashboard uses this for streaming chat replies (message_chunk / message_done frames) and voice transcripts.

Liveness and readiness

curl http://localhost:7432/health   # always 200 once the process is up
curl http://localhost:7432/ready    # 200 once startup fully completes, 503 while initializing

/health and /ready are deliberately distinct — an orchestrator that gates traffic admission on readiness (not mere liveness) should probe /ready.

Gateway status

curl http://localhost:7432/api/v1/status

{
  "status": "ok",
  "version": "2.1.5",
  "uptime_seconds": 412.3,
  "active_sessions": 2,
  "runtime_available": true,
  "init_phase": "ready",
  "voice": { "stt_available": true, "tts_available": true, "wake_word_active": false },
  "host": {
    "cpu_percent": 3.2,
    "memory_rss_bytes": 84213760,
    "disk_usage_percent": 41.7,
    "disk_free_bytes": 128849018880
  },
  "memory": { "semantic_available": true }
}

memory.semantic_available reflects whether the local embedding model (sentence-transformers) has actually loaded — true/false once known, null if no embed call has happened yet since startup. Never triggers a model load itself (that can take a while on first use); it only reports cached state. See Memory. host fields are null (not 0) when psutil isn’t installed or a read fails — that distinguishes “unavailable” from “genuinely zero.”

API sections

Chat

Send messages and stream replies.

Voice

PTT, continuous listen, wake word status.

Channels

List, enable, and disable channels.

Settings

Update LLM provider, model, thinking level, and voice settings.

Models

Provider credential status and live reachability (GET /api/v1/models).

Usage

Per-model token usage and estimated cost (GET /api/v1/usage).

MCP

Spawn and manage the MCP stdio server.

Approvals

Review pending exec commands and manage the persistent allowlist.

Privacy

Privacy settings and the (now persistent) audit log.

Provider status

curl http://localhost:7432/api/v1/models
curl "http://localhost:7432/api/v1/models?live=true"

{
  "providers": [
    { "provider": "anthropic", "configured": true, "live_checked": false, "reachable": null, "detail": "" },
    { "provider": "bedrock", "configured": null, "live_checked": false, "reachable": null, "detail": "live check not supported for this provider" }
  ]
}

configured is null only for Bedrock, whose credentials are resolved by the AWS SDK’s own chain rather than tracked by NeuralCleave directly. Reads the live runtime’s ModelRouter when a gateway is running (reflecting any settings applied via /settings/model), otherwise builds one from the on-disk config.

Usage & cost

curl http://localhost:7432/api/v1/usage

{
  "models": {
    "claude-opus-4-8": { "input_tokens": 4210, "output_tokens": 1340, "cost_usd": 0.1642 }
  },
  "total_cost_usd": 0.1642
}

A live, in-process view (resets on restart) — scrape /api/v1/metrics for long-term history.

​Base URL

​Authentication

​Response format

​Success

​Error

​WebSocket

​Liveness and readiness

​Gateway status

​API sections