Skip to content

API.md

Latest commit

 

History

History
269 lines (222 loc) · 3.69 KB

API.md

File metadata and controls

269 lines (222 loc) · 3.69 KB

goFlix API Documentation

Base URL

http://localhost:8080/api

Authentication

Most endpoints require authentication via JWT token. Include the token in the Authorization header:

Authorization: Bearer <your-token>

Endpoints

Authentication

Register

POST /auth/register
Body: {
  "username": "string",
  "email": "string",
  "password": "string" (min 8 characters)
}
Response: {
  "token": "string",
  "user": { ... },
  "expires_at": "timestamp"
}

> **Note:** After the initial admin account is created, this endpoint is disabled. Future user creation will be handled through an invite/admin interface.

#### Auth Status

GET /auth/status Response: { "needs_setup": boolean }

Login

POST /auth/login
Body: {
  "username": "string",
  "password": "string"
}
Response: {
  "token": "string",
  "user": { ... },
  "expires_at": "timestamp"
}

Media

List Media

GET /media
Query Parameters:
  - page: integer (default: 1)
  - limit: integer (default: 20)
  - type: string (movie, tv_series, documentary)
  - genre: string
  - search: string
  - sort: string (title, release_date, rating_average, created_at)
  - order: string (asc, desc)

Get Media

GET /media/:id
Response: {
  "id": "uuid",
  "title": "string",
  "overview": "string",
  "release_date": "date",
  "poster_url": "string",
  "backdrop_url": "string",
  "media_type": "string",
  "rating_average": "float",
  "genres": [...],
  "tags": [...],
  "files": [...]
}

Stream Media

GET /media/:id/stream
Returns: Video file stream

Movies

List Movies

GET /movies
Same query parameters as /media

Get Movie

GET /movies/:id

TV Series

List TV Series

GET /tv

Get TV Series

GET /tv/:id

Get Seasons

GET /tv/:id/seasons

Get Episodes

GET /tv/:id/seasons/:seasonNumber/episodes

Search

Search Media

GET /search?q=<query>

Profiles

List Profiles (Auth Required)

GET /profiles

Create Profile (Auth Required)

POST /profiles
Body: {
  "name": "string",
  "avatar_url": "string",
  "is_child": "boolean",
  "parental_rating_limit": "string"
}

Watch History

Get Watch History (Auth Required)

GET /history?profile_id=<uuid>

Update Watch History (Auth Required)

POST /history
Body: {
  "profile_id": "uuid",
  "media_id": "uuid",
  "episode_id": "uuid" (optional),
  "watched_seconds": "integer",
  "total_seconds": "integer",
  "completed": "boolean"
}

Get Continue Watching (Auth Required)

GET /history/continue?profile_id=<uuid>

Watchlist

Get Watchlist (Auth Required)

GET /watchlist?profile_id=<uuid>

Add to Watchlist (Auth Required)

POST /watchlist
Body: {
  "profile_id": "uuid",
  "media_id": "uuid"
}

Tags & Genres

List Tags

GET /tags

List Genres

GET /genres

Ratings

Create/Update Rating (Auth Required)

POST /ratings
Body: {
  "media_id": "uuid",
  "profile_id": "uuid",
  "rating": "integer" (1-10)
}

Libraries

List Libraries (Auth)

GET /libraries

Get Library

GET /libraries/:id

Create Library (Admin)

POST /libraries
Body: {
  "name": "Movies",
  "library_type": "movie" | "tv" | "music" | "photos" | "other",
  "language": "en-US",
  "paths": ["/media/movies"]
}

Update Library (Admin)

PATCH /libraries/:id

Update Library Paths (Admin)

PUT /libraries/:id/paths
Body: {
  "paths": [
    { "path": "/media/movies", "priority": 10 }
  ]
}

Trigger Library Scan (Admin)

POST /libraries/:id/scan

Recent Media in Library

GET /libraries/:id/recent