second-brain/docs/api.md

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:

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

Response:

{
  "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:

{
  "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:

{ "path": "notes/new-note.md" }

---

POST /index/reindex

Queue a full vault re-index.

Request:

{ "force": false }

Set force: true to reindex even unchanged files.

---

GET /tags

List all tags with document counts.

Response:

[
  {"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:

{
  "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:

{
  "status": "ok",
  "database": "ok",
  "ollama": "ok",
  "version": "1.0.0"
}