API Reference

All endpoints return JSON. Protected endpoints require a JWT token via Authorization: Bearer <token> header or ?token=<token> query parameter.

Authentication

Method	Endpoint	Auth	Description
`POST`	`/api/auth/setup`	No	Set initial admin password (first-boot only)
`POST`	`/api/auth/login`	No	Authenticate → returns JWT
`GET`	`/api/auth/me`	Yes	Current user info
`POST`	`/api/auth/change-password`	Yes	Change own password

POST /api/auth/login

Body:

{ "username": "alice", "password": "secret" }

Response:

{ "token": "eyJhbG...", "user": { "id": 1, "username": "alice", "isAdmin": true } }

Cloud Authentication

Method	Endpoint	Auth	Description
`POST`	`/api/auth/cloud-login`	No	Authenticate via h3xed.app cloud token
`POST`	`/api/auth/setup-from-cloud`	No	Link server to h3xed.app during initial setup

Server

Method	Endpoint	Auth	Description
`GET`	`/api/server`	No	Server name, version, platform
`GET`	`/api/status`	Yes	Detailed server status (library/user/session counts)

Libraries

Method	Endpoint	Auth	Description
`GET`	`/api/libraries`	Yes	List accessible libraries with item counts
`GET`	`/api/libraries/:id/items`	Yes	Browse items in a library (paginated)
`GET`	`/api/libraries/:id/recent`	Yes	Recently added items in a library
`POST`	`/api/libraries`	Admin	Create a new library
`PUT`	`/api/libraries/:uuid`	Admin	Update a library
`DELETE`	`/api/libraries/:uuid`	Admin	Delete a library
`POST`	`/api/libraries/:uuid/scan`	Admin	Trigger a library scan
`POST`	`/api/libraries/:uuid/refresh`	Admin	Refresh all metadata in a library
`GET`	`/api/libraries/:id/recommended`	Yes	Recommended items for a library
`GET`	`/api/scan-status`	Admin	Check scan progress

GET /api/libraries/:id/items

Query params: offset (default 0), limit (default 50)

Response:

{
  "library": { "id": "uuid", "name": "Movies", "type": "movie" },
  "items": [
    {
      "id": "rating-key",
      "type": "movie",
      "title": "Movie Title",
      "year": 2024,
      "summary": "...",
      "thumb": "/api/artwork/rating-key/thumb",
      "addedAt": 1700000000
    }
  ],
  "totalCount": 150,
  "offset": 0,
  "limit": 50
}

Invites

Method	Endpoint	Auth	Description
`POST`	`/api/invites`	Admin	Create a new invite
`GET`	`/api/invites`	Admin	List all invites
`DELETE`	`/api/invites/:id`	Admin	Revoke an invite
`POST`	`/api/invites/:token/accept`	No	Accept an invite and create account
`GET`	`/api/invite-info/:token`	No	Get server info for an invite (public)

Media

Method	Endpoint	Description
`GET`	`/api/media/:ratingKey`	Item details (movie/show)
`GET`	`/api/media/:ratingKey/children`	Seasons (show) or episodes (season)
`GET`	`/api/media/:ratingKey/episodes`	All episodes of a season
`GET`	`/api/cast/:ratingKey`	Cast and crew
`GET`	`/api/artwork/:ratingKey/thumb`	Poster image
`GET`	`/api/artwork/:ratingKey/art`	Background art

GET /api/media/:ratingKey (Movie)

{
  "id": "abc123",
  "type": "movie",
  "title": "Movie Title",
  "year": 2024,
  "summary": "...",
  "rating": 8.5,
  "duration": 7200000,
  "thumb": "/api/artwork/abc123/thumb",
  "art": "/api/artwork/abc123/art",
  "files": [
    {
      "id": 42,
      "streamUrl": "/api/stream/42",
      "container": "mkv",
      "videoCodec": "hevc",
      "audioCodec": "aac",
      "videoResolution": "1080",
      "width": 1920,
      "height": 1080
    }
  ]
}

Playback & Streaming

Method	Endpoint	Description
`GET`	`/api/stream/:fileId`	Direct play file (supports range requests)
`GET`	`/api/media/:fileId/playback-info`	Can this file direct play? Or needs transcode?
`POST`	`/api/transcode/:fileId`	Start HLS transcode session
`GET`	`/api/transcode/:sessionId/stream.m3u8`	HLS playlist
`GET`	`/api/transcode/:sessionId/:segment`	HLS segment
`DELETE`	`/api/transcode/:sessionId`	Stop transcode
`GET`	`/api/media/:fileId/info`	Full probe info (codecs, audio tracks, subtitles)
`GET`	`/api/media/:fileId/subtitle/:index`	External subtitle file (auto-converts SRT to VTT)

Watch Progress

Method	Endpoint	Description
`POST`	`/api/progress`	Report playback position
`POST`	`/api/progress/watched`	Mark as watched
`DELETE`	`/api/progress/:ratingKey`	Mark as unwatched
`GET`	`/api/continue-watching`	Items with partial progress
`GET`	`/api/watch-state?keys=a,b,c`	Batch watch state lookup

POST /api/progress

{ "ratingKey": "file-rating-key", "offset": 120000 }

Watchlist

Method	Endpoint	Description
`GET`	`/api/watchlist`	Get the current user's watchlist
`POST`	`/api/watchlist/:ratingKey`	Add an item to the watchlist
`DELETE`	`/api/watchlist/:ratingKey`	Remove an item from the watchlist

Mark Watched / Unwatched

Method	Endpoint	Description
`POST`	`/api/mark-watched/:ratingKey`	Mark an item as watched
`POST`	`/api/mark-unwatched/:ratingKey`	Mark an item as unwatched

Discovery

Method	Endpoint	Description
`GET`	`/api/search?q=query`	Search media by title
`GET`	`/api/discover/recent`	Recently added across all libraries

Users (Admin)

Method	Endpoint	Description
`GET`	`/api/users`	List all users
`POST`	`/api/users`	Create a user
`PUT`	`/api/users/:id`	Update a user
`DELETE`	`/api/users/:id`	Delete a user
`GET`	`/api/users/:id/share-link`	Generate JWT share link
`GET`	`/api/users/:id/restrictions`	Get user content restrictions
`PUT`	`/api/users/:id/restrictions`	Update user content restrictions (ratings, labels)

Admin

Method	Endpoint	Description
`GET`	`/api/hardware`	Detected transcoding hardware
`PUT`	`/api/hardware`	Update transcoder settings
`GET`	`/api/browse-fs?path=/`	Browse server filesystem
`GET`	`/api/genres`	List all genres
`GET`	`/api/logs`	Recent request logs

Metadata Management

Method	Endpoint	Description
`POST`	`/api/match/:ratingKey/search`	Search TMDb for a metadata match
`POST`	`/api/match/:ratingKey/apply`	Apply a TMDb match
`POST`	`/api/match/:ratingKey/refresh`	Refresh metadata from TMDb
`GET`	`/api/media-item/:ratingKey`	Get editable metadata
`PUT`	`/api/media-item/:ratingKey`	Manually edit metadata