# 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": true,
    "supports_transparency": true,
    "supports_tray": true,
    "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
    }
  }
}
```

## Error Response

```json
{
  "code": "unauthorized",
  "message": "missing or invalid bearer token"
}
```