Skip to content

API.md

Latest commit

 

History

History
191 lines (133 loc) · 2.81 KB

API.md

File metadata and controls

191 lines (133 loc) · 2.81 KB
Raw

PixelVault API Reference

Base URL: http://localhost:3000

All authenticated endpoints require the header:

Authorization: Bearer <jwt_token>

Auth

POST /api/users/register

Create a new account.

Body:

{ "username": "string", "password": "string" }

Response 201:

{ "token": "jwt_string", "userId": 1, "username": "string" }

POST /api/users/login

Authenticate and receive a JWT (30-day expiry).

Body:

{ "username": "string", "password": "string" }

Response 200:

{ "token": "jwt_string", "userId": 1, "username": "string" }

Media

GET /api/media

List all media items. Requires auth.

Query params: search (optional string)

Response 200:

[
  {
    "id": 1,
    "filename": "Blade Runner 2049.mkv",
    "title": "Blade Runner 2049",
    "year": 2017,
    "duration": 9720,
    "size": 15728640000,
    "thumbnail": "/thumbnails/1.jpg",
    "tmdb_id": 335984,
    "overview": "..."
  }
]

GET /api/media/scan

Trigger a library scan. Requires auth.

Response 200:

{ "message": "Scan started" }

GET /api/media/:id/progress

Get watch progress for the authenticated user.

Response 200:

{ "position": 3600, "duration": 9720 }

POST /api/media/:id/progress

Save watch progress.

Body:

{ "position": 3600, "duration": 9720 }

Streaming

GET /api/stream/:id

Stream a video file. Supports Range header for seek.

Headers: Range: bytes=0- (optional)

Response: 200 (full) or 206 (partial) with video stream.

TV Shows

GET /api/shows

List all TV shows (grouped from scanned media). Requires auth.

GET /api/shows/:id

Get show details with episodes.

Pairing

POST /api/pair/generate

Generate a QR code + 6-digit code for device pairing. Requires auth.

Response 200:

{
  "code": "ABC123",
  "qr": "data:image/png;base64,...",
  "expiresAt": "2026-06-04T10:10:00.000Z"
}

POST /api/pair/redeem

Exchange a 6-digit code for a JWT (no prior auth needed).

Body:

{ "code": "ABC123" }

Response 200:

{ "token": "jwt_string", "userId": 1, "username": "string" }

Libraries

GET /api/libraries

List all configured libraries. Requires auth.

POST /api/libraries

Create a new library. Requires auth.

Body:

{ "name": "Movies", "path": "/media/movies" }

Subtitles

GET /api/subtitles/:mediaId

List available subtitle tracks for a media item.

GET /api/subtitles/:mediaId/:track

Download a subtitle file (SRT or VTT).

Health

GET /api/health

No auth required.

Response 200:

{ "status": "ok", "service": "PixelVault", "version": "0.1.0" }