API reference

h3xed exposes a large HTTP API that the official apps run on. Most of it is internal and may change between releases — this page documents a selected, stable subset to give you a feel for the shape. It isn't exhaustive.

There are two surfaces:

Server API — on your own server (default port 32400): libraries, media, playback, profiles, restrictions, co-op
Cloud API — on h3xed.app: accounts, device pairing, friends, and watch party, served under the /cloud path prefix (e.g. https://h3xed.app/cloud/api/...)

All endpoints return JSON. Protected server endpoints require a JWT via the Authorization: Bearer <token> header or a ?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 content restrictions for an account/profile
`PUT`	`/api/users/:id/restrictions`	Set content restrictions (rating ceilings, allowed/excluded ratings & labels, allow-unrated)

PUT /api/users/:id/restrictions

Used for managed (kids) profiles. ratingCeilings takes ladder positions like PG-13 or TV-14 and is expanded server-side; allowUnrated governs items with no rating (fails closed when omitted).

{
  "ratingCeilings": ["PG-13"],
  "excludedLabels": ["adult"],
  "allowedLabels": [],
  "allowUnrated": false
}

Profiles

Method	Endpoint	Description
`GET`	`/api/profiles`	List profiles on the current account
`POST`	`/api/profiles`	Create a profile (`name`, optional `avatar`, `isManaged`, `pin`)
`PATCH`	`/api/profiles/:id`	Rename, change avatar, toggle managed, set/clear PIN
`DELETE`	`/api/profiles/:id`	Delete a profile and its watch state
`POST`	`/api/profiles/:id/switch`	Switch the active profile (PIN required if set)

Co-op

Method	Endpoint	Description
`GET`	`/api/coop/peers`	List linked co-op servers
`POST`	`/api/coop/sync`	Sync shared libraries from a peer
`POST`	`/api/coop/reconcile`	Reconcile the merged catalog (de-dup)

Cloud: device pairing

Apple TV and other devices pair through the cloud. The device requests a short user code, the user approves it from a signed-in device, and the device polls for its token. Served under /cloud on h3xed.app.

Method	Endpoint	Description
`POST`	`/api/device/code`	Start pairing → returns a user code (shown on the device) and a device code to poll with
`POST`	`/api/device/approve`	A signed-in user approves a pairing code
`POST`	`/api/device/token`	Device polls; returns an account token once approved (single use)

Cloud: friends

Method	Endpoint	Description
`GET`	`/api/friends`	List friends
`GET`	`/api/friends/requests`	Pending friend requests
`POST`	`/api/friends/requests/:id/accept`	Accept a request
`POST`	`/api/friends/requests/:id/decline`	Decline a request
`GET`	`/api/friends/blocks`	List blocked accounts
`GET`	`/api/social/presence`	Presence for your friends

Cloud: watch party

Method	Endpoint	Description
`POST`	`/api/party/rooms`	Create a watch-party room
`GET`	`/api/party/code/:code`	Look up a room by its 6-character code
`GET`	`/api/party/rooms/:id`	Room state
`POST`	`/api/party/rooms/:id/invites`	Invite a friend to the room
`POST`	`/api/party/rooms/:id/end`	End the room

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