REST API
Lumio exposes a RESTful API following HATEOAS conventions.
Base URLs
| Environment | URL |
|---|---|
| Staging | https://lumio.api.staging.zaflun.dev/v1 |
| Production Preview | https://lumio.api.prod.zaflun.dev/v1 |
| Production | coming soon — official domain not yet assigned |
Response Format
All responses follow the HATEOAS format with embedded links:
{
"data": { ... },
"_links": {
"self": { "href": "/v1/overlays/123" },
"collection": { "href": "/v1/overlays" }
}
}
Interactive Documentation
- Swagger UI — Available at
/v1/swagger-ui/when the API is running - OpenAPI spec — Download from
/v1/api-doc/openapi.json
Endpoints Overview
All paths are under /v1. Request and response bodies use snake_case. Permissions use the resource:action format.
| Resource group | Path prefix | Description |
|---|---|---|
| Auth | /v1/auth | Token exchange, refresh, logout, OAuth link/authorize |
| Users | /v1/users/me | Current-user profile, login connections, sessions |
| Accounts | /v1/accounts | Create/dissolve/leave accounts, member invites |
| Members & Invites | /v1/accounts/{id}/members, /v1/invites | Team management |
| Roles | /v1/roles | RBAC role CRUD and permission catalog |
| Tokens | /v1/tokens | Popout/API token management (/tokens/me = current permissions) |
| Overlays | /v1/overlays | Overlay configuration CRUD |
| Uploads | /v1/uploads | File uploads (multipart) and presigned download URLs |
| Chat | /v1/chat/* | History, send, moderate, user profiles, notes, raid/poll/prediction |
| Events | /v1/events | Event history, single event, emit/test |
| Emotes | /v1/emotes | Channel and user emote fetching |
| Connections | /v1/connections | App credentials and channel OAuth flow |
| Bot Connections | /v1/bot-connections, /v1/bot-status, /v1/bot-toggle, /v1/bot-rejoin | Custom bot identity OAuth and control |
| Bot Commands | /v1/bot-commands | Cross-platform command CRUD and global overrides |
| Bot Modules | /v1/bot-modules | Moderation module configs (link/spam/word/timed) |
| Automations | /v1/automations | Visual automation CRUD and manual execution |
| Channel Status | /v1/channel-status, /v1/spotify/manual-connect | Live status and Spotify manual polling |
| Spotify | /v1/spotify/* | State, playback, queue, devices, playlists, search |
| Copyright | /v1/copyright/* | Safe/blocked songs, playlist imports, community voting |
| Notifications | /v1/notifications | In-app notifications and actions |
| OBS | /v1/integrations/obs, /v1/obs-remote/* | OBS config + remote stream/recording/scene control |
| SE Tokens | /v1/se-tokens | StreamElements JWT token storage |
| Discord Guilds | /v1/discord-guilds/exchange | Discord guild bot install exchange |
| Abuse Reports | /v1/abuse-reports | User-submitted abuse reports |
| Webhooks | /v1/webhooks/* | Platform webhooks (Twitch, YouTube, Kick, Trovo, Shopify, Stripe) |
| Billing | /v1/billing/* | Stripe checkout/portal/status/invoices/coupon |
| Playlists | /v1/playlists | Read-only global safe-song playlists |
| Songs | /v1/songs | Read-only song metadata and copyright status |
| Plugins | /v1/plugins | Plugin registry (list + by type) |
| Features | /v1/features/enabled, /v1/providers/enabled | Public feature/provider flag reads |
| Health | /v1, /v1/health | Liveness probes |
| Admin | /v1/admin/* | System-admin-only endpoints (feature flags, users, accounts, OAuth clients, system keys/connections, providers, coupons, audit log, bot control) |
For the exhaustive parameter list of every endpoint, use the Swagger UI at /v1/swagger-ui/ or download /v1/api-doc/openapi.json. Feature-specific docs under Features document the most commonly used endpoints with their resource:action permissions.