# API Reference

Base URL: `http://localhost:8000/api/v1`

Interactive docs: `http://localhost:8000/docs` (Swagger UI)

---

## Authentication

No authentication is required by default (local-only deployment). Add a reverse proxy with auth for production.

---

## Endpoints

### POST `/search`

Hybrid vector + full-text search across the knowledge base.

**Request:**
```json
{
  "query": "machine learning transformers",
  "limit": 10,
  "threshold": 0.65,
  "tags": ["ml", "ai"],
  "hybrid": true
}
```

**Response:**
```json
{
  "results": [
    {
      "document_id": "uuid",
      "chunk_id": "uuid",
      "title": "Introduction to Transformers",
      "path": "resources/ml/transformers.md",
      "content": "...chunk text...",
      "score": 0.923,
      "tags": ["ml", "transformers"],
      "highlight": "...bolded match..."
    }
  ],
  "total": 5,
  "query_time_ms": 18.4
}
```

---

### POST `/chat`

RAG chat with streaming Server-Sent Events response.

**Request:**
```json
{
  "message": "What do I know about neural networks?",
  "context_limit": 5,
  "stream": true
}
```

**Response (SSE stream):**
```
data: {"type":"sources","sources":[{"title":"Neural Nets","path":"...","score":0.91}]}

data: {"type":"token","token":"Neural"}

data: {"type":"token","token":" networks"}

data: {"type":"done"}
```

---

### GET `/document/{id}`

Get a document by UUID.

**Response:** Full document object including content, frontmatter, tags.

---

### GET `/document/path/{path}`

Get a document by its vault-relative path (e.g., `resources/ml/intro.md`).

---

### GET `/document/{id}/related`

Get related documents ordered by semantic similarity.

**Query params:** `limit` (default: 5)

---

### POST `/index`

Queue a specific file for indexing.

**Request:**
```json
{ "path": "notes/new-note.md" }
```

---

### POST `/index/reindex`

Queue a full vault re-index.

**Request:**
```json
{ "force": false }
```
Set `force: true` to reindex even unchanged files.

---

### GET `/tags`

List all tags with document counts.

**Response:**
```json
[
  {"tag": "machine-learning", "count": 42},
  {"tag": "python", "count": 38}
]
```

---

### GET `/graph`

Get the knowledge graph (nodes = documents, edges = links).

**Query params:** `limit` (default: 200)

---

### GET `/stats`

System statistics.

**Response:**
```json
{
  "total_documents": 1234,
  "total_chunks": 8765,
  "total_relations": 3210,
  "total_tags": 87,
  "last_indexed": "2026-03-05T19:00:00Z",
  "embedding_model": "nomic-embed-text",
  "chat_model": "mistral"
}
```

---

### GET `/health`

Health check.

**Response:**
```json
{
  "status": "ok",
  "database": "ok",
  "ollama": "ok",
  "version": "1.0.0"
}
```