# REST API

## Base URL

```text
https://api.memside.com
```

## Authentication

```text
Authorization: Bearer mem_sk_example_key
```

Do not send API keys in query strings.

## Context and Memory routes

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/context/startup` | Load startup context. |
| `GET` | `/context/resume` | Continue from a checkpoint. |
| `GET` | `/context/workspace-profile` | Load workspace guidance. |
| `GET` | `/memories` | List Memories. |
| `GET` | `/memories/search` | Search Memories. |
| `GET` | `/memories/batch` | Get several known Memories. |
| `GET` | `/memories/{id}` | Get one Memory. |
| `POST` | `/memories` | Create a Memory. |
| `PATCH` | `/memories/{id}` | Update a Memory. |
| `DELETE` | `/memories/{id}` | Delete a Memory when allowed. |
| `GET` | `/memories/{id}/revisions` | List Memory revisions. |

### Batch-read limits

`GET /memories/batch` accepts between one and eight exact Memory IDs. Duplicate
IDs are returned once. Memory text is bounded to 2,000 characters per returned
Memory and 12,000 characters across the complete response. A body can therefore
be shortened, and later items can return a body-budget error when the total
limit has already been used.

## Subject and connected-context routes

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/subjects` | List or search Subjects. |
| `POST` | `/subjects` | Create a Subject. |
| `GET` | `/subjects/{subject_id}` | Get one Subject. |
| `PATCH` | `/subjects/{subject_id}` | Update one Subject. |
| `POST` | `/subjects/{subject_id}/deletion/prepare` | Prepare a confirmed Subject deletion. |
| `DELETE` | `/subjects/{subject_id}` | Delete a Subject after confirmation. |
| `GET` | `/subjects/{subject_id}/memories` | List Memories linked to a Subject. |
| `GET` | `/memories/{id}/subjects` | List Subjects linked to a Memory. |
| `POST` | `/subjects/{subject_id}/memories` | Link a Memory to a Subject. |
| `DELETE` | `/subjects/{subject_id}/memories/{memory_id}` | Remove a Memory link from a Subject. |
| `GET` | `/subjects/{subject_id}/context` | Load bounded Subject context. |
| `GET` | `/subjects/{subject_id}/facts` | List reviewed Subject Facts. |
| `POST` | `/subjects/{subject_id}/fact-suggestions` | Create a source-backed Fact suggestion. |
| `GET` | `/memories/{id}/context-map` | Load a bounded Context Map. |
| `GET` | `/subjects/{subject_id}/memory-insights` | List pending read-only Memory insights. |

## Library routes

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/library/templates` | Search public Library Templates. |
| `GET` | `/library/creator/status` | Review owned Templates and workflow results. |
| `POST` | `/library/templates/{template_id}/read` | Read bounded owned draft content. |
| `PUT` | `/library/templates/{template_id}/draft` | Replace an owned private draft. |
| `POST` | `/library/templates/workflow` | Create, review, publish, unpublish, or republish an owned Template. |

Read-only keys can use retrieval routes. Read-write keys are required for
changes. Library routes follow the same creator ownership and publication review
rules as the Library website.

## Search example

```bash
curl "https://api.memside.com/memories/search?q=weekend%20trip&limit=5" \
  -H "Authorization: Bearer $MEMSIDE_API_KEY"
```

## Create example

```bash
curl https://api.memside.com/memories \
  -X POST \
  -H "Authorization: Bearer $MEMSIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Weekend trip plan\nHotel confirmed. Choose activities next.",
    "type": "note",
    "sensitivity": "private",
    "tags": ["travel", "planning"]
  }'
```

## Common status codes

| Status | Meaning |
| --- | --- |
| `200` | Request succeeded. |
| `201` | A resource was created. |
| `400` | The request is invalid. |
| `401` | Credentials are missing or invalid. |
| `403` | Access is not allowed. |
| `404` | The resource was not found. |
| `429` | Too many requests. |
| `500` | Server error. |

## Error response

```json
{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "Missing credentials",
    "status": 401,
    "retryable": false
  }
}
```

## App-only features

The public API is intentionally smaller than the Memside app. Account
management, billing, private file access, and other app-only features are not
general API-key routes.

Secret Memories are excluded from public API-key access.

## Source and examples

- [Public API source documentation](https://github.com/memside/memside/blob/main/docs/public-api.md)
- [curl examples](https://github.com/memside/memside/tree/main/examples/curl)
- [JavaScript examples](https://github.com/memside/memside/tree/main/examples/javascript)

## Next steps

- [API keys](/developers/api-keys/)
- [JavaScript SDK](/developers/javascript-sdk/)
- [Python SDK](/developers/python-sdk/)
- [Library access through MCP and API](/library/mcp-and-api/)