300 lines
6.8 KiB
Markdown
300 lines
6.8 KiB
Markdown
---
|
|
sidebar_position: 4
|
|
---
|
|
|
|
# Local REST API
|
|
|
|
The MetoYou desktop app exposes an optional local HTTP API for scripts and tools. It is implemented in Electron and reads local desktop data.
|
|
|
|
## Enable the API
|
|
|
|
1. Open Settings.
|
|
2. Open Local API settings.
|
|
3. Enable the local server.
|
|
4. Choose a port. The default is `17878`.
|
|
5. Add trusted signaling server URLs for authentication.
|
|
6. Enable Scalar docs if you want `/docs`.
|
|
7. Enable Docusaurus docs if you want `/docusaurus`.
|
|
|
|
By default the server binds to `127.0.0.1`. Only enable LAN exposure when you understand the risk.
|
|
|
|
## Authentication
|
|
|
|
Protected routes require a bearer token. Get one by posting username, password, and an allowed signaling server URL.
|
|
|
|
```bash
|
|
curl -s http://127.0.0.1:17878/api/auth/login \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{
|
|
"username": "alice",
|
|
"password": "correct horse battery staple",
|
|
"serverUrl": "https://tojusignal.example.com"
|
|
}'
|
|
```
|
|
|
|
Example response:
|
|
|
|
```json
|
|
{
|
|
"token": "local_4cddf95c5b8c4b6f9e0c",
|
|
"expiresAt": 1777477200000,
|
|
"user": {
|
|
"id": "user-alice-01",
|
|
"username": "alice",
|
|
"displayName": "Alice"
|
|
}
|
|
}
|
|
```
|
|
|
|
Use the token:
|
|
|
|
```bash
|
|
curl -s http://127.0.0.1:17878/api/profile \
|
|
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
|
|
```
|
|
|
|
Logout revokes the current token:
|
|
|
|
```bash
|
|
curl -i -X POST http://127.0.0.1:17878/api/auth/logout \
|
|
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
|
|
```
|
|
|
|
## OpenAPI and Scalar
|
|
|
|
| Route | Auth | Purpose |
|
|
| --- | --- | --- |
|
|
| `GET /api/openapi.json` | No | OpenAPI 3.1 document. |
|
|
| `GET /docs` | No | Scalar API reference when enabled. |
|
|
|
|
## Public Routes
|
|
|
|
### GET /api/health
|
|
|
|
Checks whether the local API server is running.
|
|
|
|
```bash
|
|
curl -s http://127.0.0.1:17878/api/health
|
|
```
|
|
|
|
Example response:
|
|
|
|
```json
|
|
{
|
|
"status": "ok",
|
|
"version": "1.0.0",
|
|
"timestamp": 1777473600000,
|
|
"exposeOnLan": false
|
|
}
|
|
```
|
|
|
|
### GET /api/openapi.json
|
|
|
|
Returns the machine-readable API document.
|
|
|
|
```bash
|
|
curl -s http://127.0.0.1:17878/api/openapi.json
|
|
```
|
|
|
|
### POST /api/auth/login
|
|
|
|
Issues a local bearer token after credentials are validated by an allowed signaling server.
|
|
|
|
Request body:
|
|
|
|
```json
|
|
{
|
|
"username": "alice",
|
|
"password": "correct horse battery staple",
|
|
"serverUrl": "https://tojusignal.example.com"
|
|
}
|
|
```
|
|
|
|
Common errors:
|
|
|
|
| Status | Error code | Meaning |
|
|
| --- | --- | --- |
|
|
| 400 | `INVALID_REQUEST` | Missing username, password, or server URL. |
|
|
| 403 | `NO_ALLOWED_SERVERS` | No allowed signaling servers are configured. |
|
|
| 403 | `SERVER_NOT_ALLOWED` | The server URL is not in the allowed list. |
|
|
| 401 | `INVALID_CREDENTIALS` | Signaling server rejected the login. |
|
|
| 502 | `UPSTREAM_UNREACHABLE` | The signaling server could not be reached. |
|
|
|
|
## Protected Routes
|
|
|
|
All routes below require:
|
|
|
|
```http
|
|
Authorization: Bearer local_4cddf95c5b8c4b6f9e0c
|
|
```
|
|
|
|
### GET /api/profile
|
|
|
|
Reads the current local user profile.
|
|
|
|
```bash
|
|
curl -s http://127.0.0.1:17878/api/profile \
|
|
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
|
|
```
|
|
|
|
### GET /api/rooms
|
|
|
|
Lists rooms known to this device.
|
|
|
|
```bash
|
|
curl -s http://127.0.0.1:17878/api/rooms \
|
|
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
|
|
```
|
|
|
|
### GET `/api/rooms/{roomId}`
|
|
|
|
Reads one room by id.
|
|
|
|
```bash
|
|
curl -s http://127.0.0.1:17878/api/rooms/room-7ebdde75 \
|
|
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
|
|
```
|
|
|
|
### GET `/api/rooms/{roomId}/users`
|
|
|
|
Lists users known for a room.
|
|
|
|
```bash
|
|
curl -s http://127.0.0.1:17878/api/rooms/room-7ebdde75/users \
|
|
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
|
|
```
|
|
|
|
### GET `/api/rooms/{roomId}/messages`
|
|
|
|
Lists local messages for a room. `limit` defaults to `100` and is clamped from `1` to `500`. `offset` defaults to `0`.
|
|
|
|
```bash
|
|
curl -s 'http://127.0.0.1:17878/api/rooms/room-7ebdde75/messages?limit=50&offset=0' \
|
|
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
|
|
```
|
|
|
|
### GET `/api/rooms/{roomId}/messages/since`
|
|
|
|
Lists local messages after a required timestamp.
|
|
|
|
```bash
|
|
curl -s 'http://127.0.0.1:17878/api/rooms/room-7ebdde75/messages/since?sinceTimestamp=1777470000000' \
|
|
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
|
|
```
|
|
|
|
### GET `/api/rooms/{roomId}/bans`
|
|
|
|
Lists active bans for a room.
|
|
|
|
```bash
|
|
curl -s http://127.0.0.1:17878/api/rooms/room-7ebdde75/bans \
|
|
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
|
|
```
|
|
|
|
### GET `/api/rooms/{roomId}/bans/{userId}`
|
|
|
|
Checks whether a user is banned in a room.
|
|
|
|
```bash
|
|
curl -s http://127.0.0.1:17878/api/rooms/room-7ebdde75/bans/user-muse-01 \
|
|
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
|
|
```
|
|
|
|
Example response:
|
|
|
|
```json
|
|
{ "isBanned": false }
|
|
```
|
|
|
|
### GET `/api/messages/{messageId}`
|
|
|
|
Reads one local message by id.
|
|
|
|
```bash
|
|
curl -s http://127.0.0.1:17878/api/messages/msg-20260429-001 \
|
|
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
|
|
```
|
|
|
|
### GET `/api/messages/{messageId}/reactions`
|
|
|
|
Lists reactions for a message.
|
|
|
|
```bash
|
|
curl -s http://127.0.0.1:17878/api/messages/msg-20260429-001/reactions \
|
|
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
|
|
```
|
|
|
|
### GET `/api/messages/{messageId}/attachments`
|
|
|
|
Lists attachments for a message.
|
|
|
|
```bash
|
|
curl -s http://127.0.0.1:17878/api/messages/msg-20260429-001/attachments \
|
|
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
|
|
```
|
|
|
|
### GET `/api/users/{userId}`
|
|
|
|
Reads one user by id.
|
|
|
|
```bash
|
|
curl -s http://127.0.0.1:17878/api/users/user-muse-01 \
|
|
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
|
|
```
|
|
|
|
### GET /api/attachments
|
|
|
|
Lists all attachments stored on this device.
|
|
|
|
```bash
|
|
curl -s http://127.0.0.1:17878/api/attachments \
|
|
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
|
|
```
|
|
|
|
### GET /api/plugin-data
|
|
|
|
Reads a plugin data value from the local desktop database. `scope` must be `local` or `server`. Provide `serverId` when reading server-scoped data.
|
|
|
|
```bash
|
|
curl -s 'http://127.0.0.1:17878/api/plugin-data?pluginId=example.soundboard&key=favorites&scope=server&serverId=room-7ebdde75' \
|
|
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
|
|
```
|
|
|
|
Example response:
|
|
|
|
```json
|
|
{
|
|
"value": [
|
|
{ "label": "Chime", "url": "https://cdn.example.com/chime.wav" }
|
|
]
|
|
}
|
|
```
|
|
|
|
### GET `/api/meta/{key}`
|
|
|
|
Reads a desktop metadata value by key.
|
|
|
|
```bash
|
|
curl -s http://127.0.0.1:17878/api/meta/metoyou_currentUserId \
|
|
-H 'Authorization: Bearer local_4cddf95c5b8c4b6f9e0c'
|
|
```
|
|
|
|
Example response:
|
|
|
|
```json
|
|
{
|
|
"key": "metoyou_currentUserId",
|
|
"value": "user-alice-01"
|
|
}
|
|
```
|
|
|
|
## Data Model Notes
|
|
|
|
Rooms, users, messages, reactions, attachments, and bans are returned from local desktop persistence. Many schemas allow additional properties because the local database can carry richer app state than the REST docs need to guarantee.
|
|
|
|
## Security Notes
|
|
|
|
- Keep the API bound to `127.0.0.1` unless LAN access is required.
|
|
- Only add signaling servers you trust to the allowed list.
|
|
- Bearer tokens are local to the running desktop app.
|
|
- Stop the local API server to clear issued tokens. |