Media API - Plank

The Media API allows you to manage your personal media library, add content from magnet links, track downloads, and stream video.

Continue Watching

Get recently watched media items for the “Continue Watching” feature.

GET /api/media/continue-watching

Response

Returns up to 20 recently watched media items sorted by last played time.

[
  {
    "id": "clx123456",
    "type": "movie",
    "title": "Inception",
    "year": 2010,
    "posterUrl": "https://...",
    "playPosition": 3245.5,
    "playDuration": 8880,
    "lastPlayedAt": "2024-03-15T20:30:00Z"
  }
]

This endpoint returns media items that have been started (playPosition > 0) but not completed (playPosition < 90% of playDuration).

List Media

Retrieve all media items in your library.

GET /api/media

Query Parameters

type

MediaType

Filter by media type: movie or tv

Response

Returns an array of media objects.

[
  {
    "id": "clx123456",
    "type": "movie",
    "title": "Inception",
    "year": 2010,
    "status": "completed",
    "progress": 100,
    "tmdbId": 27205,
    "posterUrl": "https://...",
    "runtime": 148,
    "addedAt": "2024-03-15T10:30:00Z"
  }
]

Add Media

Add a new media item from a magnet link.

POST /api/media

Request Body

magnetLink

string

required

The magnet URI to download

type

MediaType

Media type: movie or tv. Auto-detected if not provided

tmdbId

number

TMDB ID for metadata enrichment

title

string

Media title (from browse view)

year

number

Release year

posterUrl

string

Poster image URL

backdropUrl

string

Backdrop image URL

overview

string

Media description/overview

genres

string[]

Array of genre names

certification

string

Content rating (e.g., “PG-13”, “TV-MA”)

Response

Returns the created media object with 201 Created status.

{
  "id": "clx123456",
  "type": "movie",
  "title": "Inception",
  "magnetLink": "magnet:?xt=urn:btih:...",
  "status": "added",
  "progress": 0
}

Behavior Notes

If a media item with the same infohash already exists in the profile, returns the existing item (200 OK)
For TV shows with the same tmdbId, creates a new download record linked to the existing show
Automatically starts the download in the background
Fetches metadata from TMDB if not provided
Downloads and caches poster/backdrop images

Get Media Details

Retrieve details for a specific media item.

GET /api/media/{id}

Path Parameters

string

required

Media ID

Response

{
  "id": "clx123456",
  "type": "movie",
  "title": "Inception",
  "year": 2010,
  "status": "ready",
  "progress": 100,
  "filePath": "/library/movies/Inception.mp4",
  "tmdbId": 27205,
  "runtime": 148,
  "playPosition": 3600,
  "playDuration": 8880
}

Delete Media

Delete a media item and all associated files.

DELETE /api/media/{id}

Path Parameters

string

required

Media ID

Response

Returns 204 No Content on success.

Behavior

Cancels any active downloads
Deletes all files from the file system
Removes database records

Search Library

Search your media library by title.

GET /api/media/search

Query Parameters

string

required

Search query (minimum 2 characters)

type

MediaType

Filter by type: movie or tv

Response

[
  {
    "id": "clx123456",
    "title": "Inception",
    "type": "movie",
    "year": 2010
  }
]

Get Download Progress

Get real-time download status and progress.

GET /api/media/{id}/progress

Path Parameters

string

required

Media ID

Response

status

DownloadStatus

Current download status

progress

number

Download progress (0-100)

downloadSpeed

number

Current download speed in bytes/second

uploadSpeed

number

Current upload speed in bytes/second

peers

number

Number of connected peers

isActive

boolean

Whether the download is currently active

filePath

string | null

Path to the downloaded file (when ready)

error

string | undefined

Error message if status is “error”

{
  "status": "downloading",
  "progress": 45.2,
  "downloadSpeed": 2097152,
  "uploadSpeed": 524288,
  "peers": 12,
  "isActive": true,
  "filePath": null
}

Get Playback Position

Get the saved playback position for a media item or episode.

GET /api/media/{id}/position

Path Parameters

string

required

Media ID

Query Parameters

episodeId

string

Episode ID (for TV shows)

Response

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

Update Playback Position

Save playback progress for a media item or episode.

PUT /api/media/{id}/position

Path Parameters

string

required

Media ID

Request Body

position

number

required

Playback position in seconds

duration

number

Total duration in seconds

episodeId

string

Episode ID (for TV shows)

Response

Returns 204 No Content on success.

Stream Media

Stream video content with support for range requests and transmuxing.

GET /api/media/{id}/stream
HEAD /api/media/{id}/stream

Path Parameters

string

required

Media ID

Query Parameters

episodeId

string

Episode ID (required for TV shows)

Headers

Range

string

Byte range request (e.g., “bytes=0-1023”)

Response

Returns video stream with appropriate content type:

200 OK - Full file response
206 Partial Content - Range request response
202 Accepted - Video is still buffering

Features

Supports HTTP range requests for seeking
Automatic transmuxing of MKV/AVI to MP4
Streams directly from active torrents
Falls back to library files for completed downloads
Handles client disconnections gracefully

Get TV Seasons

Get all seasons and episodes for a TV show.

GET /api/media/{id}/seasons

Path Parameters

string

required

Media ID (must be type “tv”)

Response

[
  {
    "id": "season_123",
    "mediaId": "clx123456",
    "seasonNumber": 1,
    "name": "Season 1",
    "episodes": [
      {
        "id": "ep_456",
        "seasonId": "season_123",
        "episodeNumber": 1,
        "title": "Pilot",
        "filePath": "/library/tv/Show/S01E01.mkv",
        "fileIndex": 0,
        "playPosition": 0,
        "playDuration": null
      }
    ]
  }
]

Guides

API Reference

​Continue Watching

​Response

​List Media

​Query Parameters

​Response

​Add Media

​Request Body

​Response

​Behavior Notes

​Get Media Details

​Path Parameters

​Response

​Delete Media

​Path Parameters

​Response

​Behavior

​Search Library

​Query Parameters

​Response

​Get Download Progress

​Path Parameters

​Response

​Get Playback Position

​Path Parameters

​Query Parameters

​Response

​Update Playback Position

​Path Parameters

​Request Body

​Response

​Stream Media

​Path Parameters

​Query Parameters

​Headers

​Response

​Features

​Get TV Seasons

​Path Parameters

​Response

Build docs developers (and LLMs) love

Continue Watching

Response

List Media

Query Parameters

Response

Add Media

Request Body

Response

Behavior Notes

Get Media Details

Path Parameters

Response

Delete Media

Path Parameters

Response

Behavior

Search Library

Query Parameters

Response

Get Download Progress

Path Parameters

Response

Get Playback Position

Path Parameters

Query Parameters

Response

Update Playback Position

Path Parameters

Request Body

Response

Stream Media

Path Parameters

Query Parameters

Headers

Response

Features

Get TV Seasons

Path Parameters

Response