Media server API
Outside players and library apps talk to a Muvo media server on the owner's hardware. This is not the account service at api.muvo.tv. Official Muvo players sign in as a person. An integration uses an API key.
Base URL
Use the server's own address. A local server listens on port 42000. A remote address is the hostname the owner saved for that server. The same routes answer on /api and /api/v1.
https://server.example:42000/api/v1/integrationsAPI key
The server owner creates a key in the media server under Settings → API keys. The secret starts with muvo_ and is shown once. Send it on every request:
Authorization: Bearer muvo_…A missing or unknown key returns 401 with Authentication required. A key that calls a route outside its scopes, or a route that would change the server, returns 403.
Each key has one or more of these scopes:
| Scope | Allows |
|---|---|
catalog | Read libraries, titles, seasons, music, audiobooks, photos, and search. |
play | Start playback and open the stream, remux, or smart-transcode URL. |
progress | Read and write resume position and watched state. |
Handshake
Any valid key can read the contract. version is "1".
curl -s \
-H "Authorization: Bearer muvo_…" \
https://server.example:42000/api/v1/integrationsThe JSON lists the scopes and the webhook event names below.
Catalog
Requires the catalog scope. These are reads.
| Method | Path |
|---|---|
| GET | /api/v1/libraries and /api/v1/libraries/list |
| GET | /api/v1/libraries/{libraryId}/items |
| GET | /api/v1/media — query type, page, pageSize or limit, search, sort |
| GET | /api/v1/media/{id} |
| GET | /api/v1/media/{id}/seasons, …/seasons/{n}/episodes, …/chapters, …/markers, …/next-episode, …/similar, …/related, …/recommendations, …/trailers, …/extras, …/variants, …/availability, …/thumbnail |
| GET | /api/v1/media/continue-watching, recently-added, trending, recommended, based-on-activity, stats, filters, home-tags |
| GET | /api/v1/search, /api/v1/genres, /api/v1/trending |
| GET | /api/v1/music/… — artists, albums, tracks, and their images |
| GET | /api/v1/audiobooks, /api/v1/audiobooks/{id}, covers and people |
| GET | /api/v1/photos/albums and /api/v1/photos/albums/{id} |
A title record includes its poster and backdrop fields. Title thumbnail bytes are GET /api/v1/media/{id}/thumbnail.
Play
Requires the play scope. Ask the server how to play a title, then open the URL it returns.
curl -s -X POST \
-H "Authorization: Bearer muvo_…" \
-H "Content-Type: application/json" \
-d '{"mediaId":"ITEM_ID"}' \
https://server.example:42000/api/v1/stream/negotiateA successful body has success: true and data.streamUrl, data.mode (direct-play, remux, audio-transcode, or server-transcode), data.sessionId, and data.startPositionMs. Send startPositionMs in the request to resume. The stream URL already includes that start when the server is remuxing or transcoding. Play that URL from the beginning. Do not seek the player to the same resume time again.
These reads also use the play scope:
GET /api/v1/media/streamGET /api/v1/media/{id}/smart-transcode,remux,transcode-stream,align-startGET /api/v1/media/{id}/subtitles/{index}— the cue file. Search and download are not on this key.GET /api/v1/audiobooks/{id}/streamGET /api/v1/photos/{id}/image
Progress
Requires the progress scope.
| Method | Path |
|---|---|
| GET, PUT | /api/v1/progress/{mediaId} — PUT JSON position and duration in seconds, optional completed |
| GET, POST | /api/v1/media/{id}/progress — same position fields |
| GET, POST, DELETE | /api/v1/media/{id}/watched |
| GET | /api/v1/media/{id}/watched-status |
| POST | /api/v1/playback/progress and /api/v1/playback/stopped |
Webhooks
The owner can turn on webhooks and save an HTTPS URL. Muvo POSTs JSON when one of these events happens. The request header is X-Muvo-Event.
{
"event": "library.new",
"timestamp": "2026-11-17T23:00:00.0000000+00:00",
"serverId": "…",
"data": { "mediaId": "…", "title": "…", "type": "movie", "libraryId": "…" }
}library.new— a title was added.datahasmediaId,title,type, andlibraryId.media.watched—data.mediaId.media.scrobble— the watch passed the end of the file.datahasmediaId,position, andduration.
What a key cannot do
A key cannot change libraries, scans, people, server settings, or backups. Those routes answer 403 with API keys cannot change this server. Account, billing, and sign-in live on auth.muvo.tv and api.muvo.tv and do not accept this key.
Infuse, Seerr, and Overseerr do not call this API yet. A player or request app integrates by speaking this contract to the media server.