Sprimo/docs/API_SPEC.md

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:

{
  "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

{
  "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

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