# 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)

```json
{
  "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)

```json
{
  "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:

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

Success response:

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

### Logout

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

Response:

```json
{
  "authenticated": false
}
```

### Session Check

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

Success response:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

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

Response:

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