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

# REST API 参考

> 当前 Memorose v1 HTTP API 的端点参考。

# REST API 参考

API 基础地址：

```text theme={null}
http://127.0.0.1:3000
```

## 认证

当前 `/v1` 路由支持两种认证方式：

* `Authorization: Bearer <dashboard-jwt>`
* `x-api-key: <api-key>`

本地开发最快的方式是：

```http theme={null}
POST /v1/dashboard/auth/login
```

<Note>
  旧示例中出现的 `/api/v1/*`、`/v1/memories`、`/v1/search` 或 `/health` 都来自更早的产品模型，不应再用于当前集成。
</Note>

## 路由分组

### 公开登录

| Method | Endpoint                   | 用途                     |
| ------ | -------------------------- | ---------------------- |
| `POST` | `/v1/dashboard/auth/login` | 获取 dashboard JWT token |

### 记忆运行时

| Method | Endpoint                                             | 用途                        |
| ------ | ---------------------------------------------------- | ------------------------- |
| `POST` | `/v1/users/:user_id/streams/:stream_id/events`       | 写入单个事件                    |
| `POST` | `/v1/users/:user_id/streams/:stream_id/events/batch` | 批量写入事件                    |
| `POST` | `/v1/users/:user_id/streams/:stream_id/retrieve`     | 混合检索                      |
| `POST` | `/v1/memory/context`                                 | 将检索结果渲染为紧凑 text 或 XML 上下文 |
| `POST` | `/v1/users/:user_id/graph/edges`                     | 添加图边                      |
| `GET`  | `/v1/status/pending`                                 | 待处理事件积压                   |

### 记忆维护

| Method   | Endpoint                                       | 用途          |
| -------- | ---------------------------------------------- | ----------- |
| `DELETE` | `/v1/users/:user_id/memories/:id`              | 硬删除单个记忆单元   |
| `POST`   | `/v1/users/:user_id/memories/semantic/preview` | 预览语义更新或遗忘计划 |
| `POST`   | `/v1/users/:user_id/memories/semantic/execute` | 执行审核后的语义计划  |

### 任务与目标

| Method | Endpoint                                           | 用途             |
| ------ | -------------------------------------------------- | -------------- |
| `GET`  | `/v1/users/:user_id/streams/:stream_id/tasks/tree` | 单个 stream 的任务树 |
| `GET`  | `/v1/users/:user_id/tasks/tree`                    | 单个用户的所有任务树     |
| `GET`  | `/v1/users/:user_id/tasks/ready`                   | 可执行任务          |
| `PUT`  | `/v1/users/:user_id/tasks/:task_id/status`         | 更新任务状态         |

### 组织知识

| Method | Endpoint                                      | 用途       |
| ------ | --------------------------------------------- | -------- |
| `GET`  | `/v1/organizations/:org_id/knowledge`         | 列出组织知识   |
| `GET`  | `/v1/organizations/:org_id/knowledge/:id`     | 获取单条知识记录 |
| `GET`  | `/v1/organizations/:org_id/knowledge/metrics` | 组织知识指标   |

### 集群操作

| Method   | Endpoint                     | 用途      |
| -------- | ---------------------------- | ------- |
| `POST`   | `/v1/cluster/initialize`     | 手动初始化集群 |
| `POST`   | `/v1/cluster/join`           | 将节点加入集群 |
| `DELETE` | `/v1/cluster/nodes/:node_id` | 从集群移除节点 |

## 集成说明

* 当前模型里的 `stream_id` 是 UUID 路径参数。
* 单节点默认部署下，Raft 自动引导默认开启。
* `memory_type` 的序列化值是 `factual` 和 `procedural`。
* 以 `crates/memorose-server/src/main.rs` 和 `crates/memorose-server/src/types.rs` 作为路由和 payload 的权威来源。
* 以 `crates/memorose-common/src/config.rs` 作为运行时配置 schema 的权威来源。