> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuralcleave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> NeuralCleave REST API — base URL, authentication, and response format.

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

```json theme={null}
{
  "field": "value"
}
```

### Error

```json theme={null}
{
  "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

```bash theme={null}
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

```bash theme={null}
curl http://localhost:7432/api/v1/status
```

```json theme={null}
{
  "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](/memory).

`host` fields are `null` (not `0`) when `psutil` isn't installed or a read fails — that distinguishes "unavailable" from "genuinely zero."

## API sections

<CardGroup cols={2}>
  <Card title="Chat" icon="comments" href="/api-reference/chat">
    Send messages and stream replies.
  </Card>

  <Card title="Voice" icon="microphone" href="/api-reference/voice">
    PTT, continuous listen, wake word status.
  </Card>

  <Card title="Channels" icon="plug" href="/api-reference/channels">
    List, enable, and disable channels.
  </Card>

  <Card title="Settings" icon="gear" href="/api-reference/settings">
    Update LLM provider, model, thinking level, and voice settings.
  </Card>

  <Card title="Models" icon="server" href="/api-reference/overview#provider-status">
    Provider credential status and live reachability (`GET /api/v1/models`).
  </Card>

  <Card title="Usage" icon="chart-line" href="/api-reference/overview#usage--cost">
    Per-model token usage and estimated cost (`GET /api/v1/usage`).
  </Card>

  <Card title="MCP" icon="server" href="/api-reference/mcp">
    Spawn and manage the MCP stdio server.
  </Card>

  <Card title="Approvals" icon="shield-check" href="/api-reference/approvals">
    Review pending exec commands and manage the persistent allowlist.
  </Card>

  <Card title="Privacy" icon="lock" href="/api-reference/privacy">
    Privacy settings and the (now persistent) audit log.
  </Card>
</CardGroup>

## Provider status

```bash theme={null}
curl http://localhost:7432/api/v1/models
curl "http://localhost:7432/api/v1/models?live=true"
```

```json theme={null}
{
  "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

```bash theme={null}
curl http://localhost:7432/api/v1/usage
```

```json theme={null}
{
  "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.