# NeuroVault REST API Reference

This document covers the main REST endpoints exposed by `neurovault serve`.

Base URL (default): `http://127.0.0.1:8787`

## Authentication

NeuroVault uses token auth for protected endpoints.

- Header: `Authorization: Bearer <token>`
- Bootstrap (first admin user): `X-Neurovault-Bootstrap-Token: <NEUROVAULT_BOOTSTRAP_TOKEN>`

## OpenAPI

FastAPI serves OpenAPI by default:

- `GET /openapi.json`
- `GET /docs`

## Health and Metrics

| Endpoint | Method | Description |
| --- | --- | --- |
| `/api/v1/health` | GET | Liveness check |
| `/api/v1/health/ready` | GET | Readiness check |
| `/metrics` | GET | Prometheus metrics |
| `/api/v1/metrics` | GET | Prometheus metrics alias |

## Core Memory Endpoints

### Ingest Memory

`POST /api/v1/ingest`

Request body:

```json
{
  "content": "User prefers dark mode",
  "source": "api",
  "importance": 0.8,
  "metadata": {
    "channel": "chat"
  }
}
```

Response:

```json
{
  "id": "<hex-memory-id>",
  "content": "User prefers dark mode",
  "source": "api"
}
```

### Recall Memory

`GET /api/v1/recall?q=<query>&mode=multi&limit=10&since=<optional_ms>`

Response item schema:

```json
{
  "id": "<hex-memory-id>",
  "content": "...",
  "score": 0.91,
  "type": "multi-signal"
}
```

### Consolidate

`POST /api/v1/consolidate`

Request body (optional):

```json
{
  "force": true,
  "phases": ["entities", "insights", "promote", "decay"]
}
```

Response:

```json
{
  "entities_extracted": 12,
  "relationships_found": 8,
  "clusters_formed": 3,
  "insights_generated": 2,
  "cross_domain_insights": 1,
  "memories_promoted": 4,
  "memories_decayed": 6,
  "memories_archived": 1,
  "duration_seconds": 0.42
}
```

### Predictions

- `GET /api/v1/predictions`
- `GET /api/v1/predictions/calendar`

### Stats and Status

- `GET /api/v1/stats`
- `GET /api/v1/status`
- `GET /api/v1/insights`
- `GET /api/v1/review`

## Entity and Graph Endpoints

- `GET /api/v1/entities?entity_type=<type>&limit=50`
- `GET /api/v1/entities/{entity_id}/relationships`
- `GET /api/v1/entities/{entity_id}/hierarchy`
- `GET /api/v1/entities/{entity_name}/graph?depth=2`
- `GET /api/v1/entities/id/{entity_id}/graph?depth=2`
- `GET /api/v1/relationships?entity_name=<name>`
- `GET /api/v1/concepts/tree?limit=200`

## Security and Admin Endpoints

Requires manage/admin permissions.

- `POST /api/v1/admin/users`
- `GET /api/v1/admin/users`
- `POST /api/v1/admin/users/{username}/revoke`
- `POST /api/v1/admin/device-token`
- `GET /api/v1/audit/log`
- `GET /api/v1/audit`

## Network and Sync Endpoints

- `GET /api/v1/network/device`
- `GET /api/v1/network/sync/status`
- `POST /api/v1/network/sync/bundle`
- `POST /api/v1/network/sync/apply`
- `POST /api/v1/network/sync/peer`
- `POST /api/v1/sync/push`
- `POST /api/v1/sync/pull`

## Persona and Checkpoint Endpoints

- `GET /api/v1/personas`
- `POST /api/v1/personas`
- `PUT /api/v1/personas/active`
- `DELETE /api/v1/personas/{name}`
- `POST /api/v1/merge`
- `POST /api/v1/checkpoint`
- `GET /api/v1/checkpoints/diff`
- `POST /api/v1/revert`
- `POST /api/v1/milestones`
- `GET /api/v1/milestones`

## Plugin and Event Endpoints

- `GET /api/v1/events`
- `GET /api/v1/plugins`
- `GET /api/v1/plugins/local`
- `GET /api/v1/plugins/{plugin_id}`
- `POST /api/v1/plugins/{plugin_id}/activate`
- `POST /api/v1/plugins/{plugin_id}/deactivate`
- `POST /api/v1/plugins/{plugin_id}/enable`
- `POST /api/v1/plugins/{plugin_id}/disable`

## Mobile API (Companion App)

Created through `create_mobile_app(...)` / `create_mobile_api(...)`:

- `GET /api/v1/health`
- `GET /api/v1/stats`
- `POST /api/v1/recall`
- `POST /api/v1/ingest`
- `GET /api/v1/entities`
- `GET /api/v1/predictions`
- `POST /api/v1/consolidate`

Requires bearer token and permission checks in mobile mode.
