> ## 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

> Current endpoint reference for the Memorose v1 HTTP API.

# REST API Reference

Base API URL:

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

## Authentication

Current `/v1` routes accept either:

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

For local development, the fastest path is:

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

<Note>
  Older examples that use `/api/v1/*`, `/v1/memories`, `/v1/search`, or `/health` are from an older product model and should not be used for current integrations.
</Note>

## Route groups

### Public login

| Method | Endpoint                   | Purpose                 |
| ------ | -------------------------- | ----------------------- |
| `POST` | `/v1/dashboard/auth/login` | Get dashboard JWT token |

### Memory runtime

| Method | Endpoint                                             | Purpose                                                  |
| ------ | ---------------------------------------------------- | -------------------------------------------------------- |
| `POST` | `/v1/users/:user_id/streams/:stream_id/events`       | Ingest one event                                         |
| `POST` | `/v1/users/:user_id/streams/:stream_id/events/batch` | Ingest a batch of events                                 |
| `POST` | `/v1/users/:user_id/streams/:stream_id/retrieve`     | Hybrid retrieval                                         |
| `POST` | `/v1/memory/context`                                 | Render retrieved memory into compact text or XML context |
| `POST` | `/v1/users/:user_id/graph/edges`                     | Add graph edge                                           |
| `GET`  | `/v1/status/pending`                                 | Pending event backlog                                    |

### Memory maintenance

| Method   | Endpoint                                       | Purpose                                    |
| -------- | ---------------------------------------------- | ------------------------------------------ |
| `DELETE` | `/v1/users/:user_id/memories/:id`              | Hard-delete one memory unit                |
| `POST`   | `/v1/users/:user_id/memories/semantic/preview` | Preview semantic update or forgetting plan |
| `POST`   | `/v1/users/:user_id/memories/semantic/execute` | Execute a reviewed semantic plan           |

### Tasks and goals

| Method | Endpoint                                           | Purpose                     |
| ------ | -------------------------------------------------- | --------------------------- |
| `GET`  | `/v1/users/:user_id/streams/:stream_id/tasks/tree` | Task tree for one stream    |
| `GET`  | `/v1/users/:user_id/tasks/tree`                    | All task trees for one user |
| `GET`  | `/v1/users/:user_id/tasks/ready`                   | Ready-to-run tasks          |
| `PUT`  | `/v1/users/:user_id/tasks/:task_id/status`         | Update task status          |

### Organization knowledge

| Method | Endpoint                                      | Purpose                        |
| ------ | --------------------------------------------- | ------------------------------ |
| `GET`  | `/v1/organizations/:org_id/knowledge`         | List organization knowledge    |
| `GET`  | `/v1/organizations/:org_id/knowledge/:id`     | Fetch one knowledge record     |
| `GET`  | `/v1/organizations/:org_id/knowledge/metrics` | Organization knowledge metrics |

### Cluster operations

| Method   | Endpoint                     | Purpose                     |
| -------- | ---------------------------- | --------------------------- |
| `POST`   | `/v1/cluster/initialize`     | Manually initialize cluster |
| `POST`   | `/v1/cluster/join`           | Join node to cluster        |
| `DELETE` | `/v1/cluster/nodes/:node_id` | Remove node from cluster    |

## Integration notes

* `stream_id` is a UUID path parameter in the current model.
* For single-node default deployments, Raft auto-bootstrap is enabled by default.
* `memory_type` values are serialized as `factual` and `procedural`.
* Treat `crates/memorose-server/src/main.rs` and `crates/memorose-server/src/types.rs` as the authoritative route and payload definitions.
* Treat `crates/memorose-common/src/config.rs` as the authoritative runtime config schema.