linearvoid/API.md

API Reference

This document describes the currently implemented API surfaces in Linear Void.

Base URLs

• Public app and admin: https://linearvoid.tv
• WebSocket endpoint: wss://linearvoid.tv/ws
• Local fallback: http://localhost and ws://localhost/ws

Authentication Model

Admin REST endpoints use a cookie session.

• Cookie name: linearvoid_admin_session
• Cookie attributes: HttpOnly, SameSite=Strict, Secure when request is HTTPS (or X-Forwarded-Proto=https)
• Session TTL: controlled by ADMIN_SESSION_TTL_HOURS (default 12h)

Chat WebSocket API

Connect

Endpoint:

• GET /ws?username={name}&room={room}

Client sends JSON messages over the socket.

Message Envelope (client -> server)

{
  "room": "main",
  "username": "viewer123",
  "text": "hello world",
  "type": "public"
}

Notes:

• type is usually public for room chat and private for DM room routing.
• Private room names are formatted like dm:userA-userB (sorted usernames).
• Moderation/system events are sent as type=system messages.

Message Envelope (server -> client)

{
  "room": "main",
  "username": "viewer123",
  "text": "hello world",
  "type": "public",
  "timestamp": "2026-08-04T12:34:56Z"
}

Admin Session API

Login

• POST /api/admin/login
• Auth: none

Request:

{
  "username": "admin",
  "password": "your-password"
}

Success response:

{
  "authenticated": true,
  "username": "admin"
}

Logout

• POST /api/admin/logout
• Auth: optional (clears cookie either way)

Response:

{
  "authenticated": false
}

Session Check

• GET /api/admin/session
• Auth: cookie required

Success response:

{
  "authenticated": true,
  "username": "admin"
}

Failure:

• 401 unauthorized

Admin Data API

All endpoints below require admin authentication.

Overview

• GET /api/admin/overview

Returns aggregate counters and runtime/system snapshot fields.

Playlist

• GET /api/admin/playlist
• PUT /api/admin/playlist

PUT request:

{
  "content": "file '/app/media/video1.mp4'\nfile '/app/media/video2.mp4'\n"
}

Schedule

• GET /api/admin/schedule

Returns parsed playlist entries plus matched media metadata/runtime.

Moderation

• GET /api/admin/moderation/logs?limit=50
• POST /api/admin/moderation/actions

Action request:

{
  "action": "mute",
  "target": "username-or-id",
  "moderator": "admin",
  "reason": "spam",
  "room": "main"
}

Analytics

• GET /api/admin/analytics

Returns totals (messages, moderation actions, rooms) and top room summary.

System

• GET /api/admin/system

Returns service health snapshot for chat/playout/redis/database and config metadata.

Active Users

• GET /api/admin/users

Returns currently discovered presence users (room + username) when Redis is available.

Media Library API

Media Collection

• GET /api/admin/media
• POST /api/admin/media (multipart upload, legacy path)

Multipart form field name: file

Media Item

• GET /api/admin/media/{id}
• PUT /api/admin/media/{id}
• DELETE /api/admin/media/{id}

PUT request:

{
  "status": "ready",
  "title": "My Clip",
  "tags": "music,live"
}

Resumable Upload API

Maximum file size: 2GB

Default chunk size: 8MB

Initialize or Resume Session

• POST /api/admin/media/uploads

Request:

{
  "uploadId": "optional-existing-id",
  "fileName": "clip.mp4",
  "fileSize": 123456789,
  "mimeType": "video/mp4",
  "chunkSize": 8388608,
  "totalChunks": 15
}

Response:

{
  "uploadId": "hex-token",
  "fileName": "clip.mp4",
  "fileSize": 123456789,
  "chunkSize": 8388608,
  "totalChunks": 15,
  "uploadedChunks": 3,
  "progress": 20
}

Check Upload Status

• GET /api/admin/media/uploads/{uploadId}

Returns same status envelope as initialize.

Upload Chunk

• PUT /api/admin/media/uploads/{uploadId}/chunk?index={chunkIndex}
• Content-Type: application/octet-stream

Response returns updated upload status envelope.

Complete Upload

• POST /api/admin/media/uploads/{uploadId}/complete

On success returns admin media listing payload (files + generatedAt).

Metrics and Health

Chat metrics

• GET /metrics

Prometheus exposition includes connected clients, stored messages, moderation actions, Redis indicators, active admin sessions, and build info.

Health

• GET /health on chat service
• GET /health on playout service
• GET /health on nginx reverse proxy

HTTP Status Conventions

• 200/201: successful request
• 400: malformed payload, invalid input, missing required fields
• 401: unauthorized admin request
• 404: not found
• 405: method not allowed
• 409: logical conflict (for example, mismatched resumed upload)
• 413: payload too large
• 500: internal server error