# md-vector-db API 参考文档

## REST API

- **Base URL**: `http://localhost:8000/api/v1`
- **认证**: `X-API-Key` Header（取决于 `MD_VECTOR_API_KEY` 环境变量）
- **速率限制**: 60s 窗口内最多 30 请求

### GET /health — 健康检查

无需认证。

```json
{
  "status": "ok",
  "checks": {
    "chromadb": {"status": "ok", "count": 1240},
    "embedder": {"status": "ok", "dimension": 512}
  }
}
```

### GET /collections — 列出集合

需 API Key。返回 `{"collections": [{"name": "...", "count": N}, ...]}`。

### POST /search — 语义检索

| 字段 | 类型 | 必填 | 约束 |
|------|------|------|------|
| query | string | ✅ | 1-2000 字符 |
| top_k | int | ❌ | 1-100，默认 10 |
| collection | string | ❌ | ≤128 字符 |

返回 `{"results": [...], "collection": "..."}`，每条结果含 `id`, `content`, `source_file`, `section_title`, `heading_level`, `score`。

### POST /ingest — 入库文档

| 字段 | 类型 | 必填 | 约束 |
|------|------|------|------|
| file_path | string | 二选一 | 安全路径 |
| content | string | 二选一 | ≤500KB |
| file_name | string | 推荐 | 1-255 字符 |
| collection | string | ❌ | ≤128 字符 |

返回 `{"status": "ok", "chunks": N, "file": "...", "collection": "..."}`。

### DELETE /documents/{file_name} — 删除文档

查询参数: `collection` (可选)。

| 状态码 | 含义 |
|--------|------|
| 200 | 删除成功 |
| 400 | file_name 不合法 |
| 401 | API Key 无效 |
| 404 | 文档不存在 |

## CLI 命令

```bash
md-vector-db ingest <文件> --incremental --force
md-vector-db ingest-dir <目录> -C <集合>
md-vector-db search "<查询>" -k 10 --mode hybrid --json
md-vector-db stats -C <集合>
md-vector-db export -o output.json -f json
md-vector-db serve -p 8000
```