86 lines
1.9 KiB
Markdown
86 lines
1.9 KiB
Markdown
# Sprimo Frontend API Specification (v1)
|
|
|
|
Base URL: `http://127.0.0.1:<port>`
|
|
|
|
Auth: `Authorization: Bearer <token>` required on all endpoints except `/v1/health`.
|
|
|
|
## Endpoints
|
|
|
|
### `GET /v1/health`
|
|
|
|
- Auth: none
|
|
- Response `200`:
|
|
|
|
```json
|
|
{
|
|
"version": "0.1.0",
|
|
"build": "dev",
|
|
"uptime_seconds": 12,
|
|
"active_sprite_pack": "default",
|
|
"capabilities": {
|
|
"supports_click_through": false,
|
|
"supports_transparency": true,
|
|
"supports_tray": false,
|
|
"supports_global_hotkey": true,
|
|
"supports_skip_taskbar": true
|
|
}
|
|
}
|
|
```
|
|
|
|
### `GET /v1/state`
|
|
|
|
- Auth: required
|
|
- Response `200`: current frontend snapshot.
|
|
- Response `401`: missing/invalid token.
|
|
- Includes optional `last_error` diagnostic field for latest runtime command-application error.
|
|
|
|
### `POST /v1/command`
|
|
|
|
- Auth: required
|
|
- Body: one command envelope.
|
|
- Response `202`: accepted.
|
|
- Response `400`: malformed JSON.
|
|
- Response `401`: missing/invalid token.
|
|
- Runtime note for `SetSpritePack`:
|
|
- successful load switches sprite atlas immediately.
|
|
- failed load keeps current in-memory sprite/animation unchanged and reports the failure via `/v1/state.last_error`.
|
|
|
|
### `POST /v1/commands`
|
|
|
|
- Auth: required
|
|
- Body: ordered array of command envelopes.
|
|
- Response `202`: accepted.
|
|
- Response `400`: malformed JSON.
|
|
- Response `401`: missing/invalid token.
|
|
- Commands are applied in-order by the frontend runtime after transport acceptance.
|
|
|
|
## Command Envelope
|
|
|
|
```json
|
|
{
|
|
"id": "2d95f8a8-65cc-4309-8f76-4881949d7f4b",
|
|
"ts_ms": 1737000000000,
|
|
"command": {
|
|
"type": "set_state",
|
|
"payload": {
|
|
"state": "active",
|
|
"ttl_ms": null
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Compatibility Notes
|
|
|
|
- `SetFlags.click_through` is deprecated for compatibility and ignored at runtime.
|
|
- Frontend state always reports `flags.click_through = false`.
|
|
|
|
## Error Response
|
|
|
|
```json
|
|
{
|
|
"code": "unauthorized",
|
|
"message": "missing or invalid bearer token"
|
|
}
|
|
```
|