tinyMediaManager provides a powerful HTTP API for remote control and automation. This documentation describes the available endpoints, actions, scopes, and arguments, as well as example requests.

Enabling the API

After enabling the HTTP API you can send requests to the chosen port. Make sure you add the API key in the header field api-key to all requests.

Command structure

The HTTP API supports to send multiple commands via a POST request (JSON body) at once. Every command follows the same structure:

{
  "action": <action name>,
  "scope": {
    "name": <scope name>,
    "args": [
      <value>  
    ]
  },
  "args": {
    <key>: <value>  
  }
}
  • action: The name of the action to trigger - you will find all implemented actions below
  • scope: The scope for the action. This defines on which entries the action should be applied. The optional parameter args can be used to fine-tune the scope (not available on all scope values). Valid scope values depend on the action you trigger (details see below).
  • args: Any extra arguments you may pass to the actions (optional - used by some actions)

When sending multiple commands, the order of execution may be different to the order in the request. tinyMediaManager makes sure the commands will be executed in the right order to preserve the best possible result.

When sending a new call, all new flags from any previous calls are dropped. If you want to do follow-up actions for newly found entries, you need combine all action into one call!

Movies

These actions are executed in the movie module. To send a command to the movie module, you need to use the subpath movie (e.g. http://localhost:7878/api/movie).

Update data sources

Trigger the update data source action. This scans your data sources for new movies.

Example JSON:

{
  "action": "update",
  "scope": { "name": "all" }
}
  • action - update
  • scope
    • all- update all data sources.
    • single- update a single data source. The indices for identifying the data source(s) will be used from args (multiple, starting with 0 for the first data source in your settings).

Reload media info

v5.0.10 Trigger the reload media info action. This reloads media info of all your media files (respecting mediainfo.xml files).

Example JSON:

{
  "action": "reloadMediaInfo",
  "scope": { "name": "all" }
}
  • action - reloadMediaInfo
  • scope
    • new or empty - scrape all new movies. Any movie which has been added in the last update data source action will be classified as new.
    • path- scrape all movies from the given path(s). You can pass the path(s) via args (multiple, no subpath possible).
    • dataSource- scrape all movies from the given data source(s). You can pass the data sources via args (multiple, either index of the data source or the path itself).
    • unscraped - scrape all items which are not scraped
    • all- scrape all movies.

Detect aspect ratio

v5.0.10 Trigger the detect aspect ratio action. This command will run the aspect ratio detector (using FFmpeg) for your movies.

Example JSON:

{
  "action": "detectAspectRatio",
  "scope": { "name": "all" }
}
  • action - detectAspectRatio
  • scope
    • new or empty - scrape all new movies. Any movie which has been added in the last update data source action will be classified as new.
    • path- scrape all movies from the given path(s). You can pass the path(s) via args (multiple, no subpath possible).
    • dataSource- scrape all movies from the given data source(s). You can pass the data sources via args (multiple, either index of the data source or the path itself).
    • unscraped - scrape all items which are not scraped
    • all- scrape all movies.

Scrape

Scrape your movies from online sources.

Example JSON:

{
  "action": "scrape",
  "scope": { "name": "all" },
  "args": { "scraper": "tmdb" }
}
  • action - scrape
  • scope
    • new or empty - scrape all newly added movies. Any movie added during the update data source action of the current API call will be considered new.
    • path - scrape all movies from the specified path(s). Provide the path(s) via args (multiple allowed, no subpath possible).
    • dataSource - scrape all movies from the specified data source(s). Provide the data sources via args (multiple allowed, either the index of the data source or the path itself).
    • unscraped - scrape all movies that have not yet been scraped.
    • all - scrape all movies.
  • args
    • scraper (tmdb, imdb, tvdb, trakt, universal_movie, omdbapi, ofdb, moviemeter, mpdbtv, …) - use the specified scraper (optional; if omitted, the scraper from the settings will be used).

Fetch ratings

Fetch ratings for your movies

Example JSON:

{
  "action": "fetchRatings",
  "scope": { "name": "all" }
}
  • action - fetchRatings
  • scope
    • new or empty - fetch ratings for all new movies. Any movie which has been added in the last update data source action will be classified as new.
    • path- fetch ratings for all movies from the given path(s). You can pass the path(s) via args (multiple, no subpath possible).
    • dataSource- fetch ratings for all movies from the given data source(s). You can pass the data sources via args (multiple, either index of the data source or the path itself).
    • unscraped - fetch ratings for all items which are not scraped
    • all- fetch ratings for all movies.

Trailer download

Download trailers.

Example JSON:

{
  "action": "downloadTrailer",
  "scope": { "name": "all" },
  "args": { "onlyMissing": true }
}
  • action - downloadTrailer
  • scope
    • new or empty - download trailers for all new movies. Any movie which has been added in the last update data source action will be classified as new.
    • path- download trailers for all movies from the given path(s). You can pass the path(s) via args (multiple, no subpath possible).
    • dataSource- download trailers for all movies from the given data source(s). You can pass the data sources via args (multiple, either index of the data source or the path itself).
    • all- download trailers for all movies.
  • args
    • onlyMissing (true/false) - only download missing trailers (optional, defaults to true if omitted).

Subtitle download

Download subtitles.

Example JSON:

{
  "action": "downloadSubtitle",
  "scope": { "name": "all" },
  "args": { "language": "en", "onlyMissing": true }
}
  • action - downloadSubtitle
  • scope
    • new or empty - download subtitles for all new movies. Any movie which has been added in the last update data source action will be classified as new.
    • path- download subtitles for all movies from the given path(s). You can pass the path(s) via args (multiple, no subpath possible).
    • dataSource- download subtitles for all movies from the given data source(s). You can pass the data sources via args (multiple, either index of the data source or the path itself).
    • all- download subtitles for all movies.
  • args
    • language (ISO code) - the language to download the subtitles for (optional, defaults to the language of the settings if omitted).
    • onlyMissing (true/false) - only download missing subtitles (optional, defaults to true if omitted).

Download missing artwork

Download missing artwork for movies.

Example JSON:

{
  "action": "downloadMissingArtwork",
  "scope": { "name": "all" }
}
  • action - downloadMissingArtwork
  • scope
    • new or empty - fetch ratings for all new movies. Any movie which has been added in the last update data source action will be classified as new.
    • path- fetch ratings for all movies from the given path(s). You can pass the path(s) via args (multiple, no subpath possible).
    • dataSource- fetch ratings for all movies from the given data source(s). You can pass the data sources via args (multiple, either index of the data source or the path itself).
    • unscraped - fetch ratings for all items which are not scraped
    • all- fetch ratings for all movies.

Rename

Rename your movies according to your renamer patterns.

Example JSON:

{
  "action": "rename",
  "scope": { "name": "all" }
}
  • action - rename
  • scope
    • new or empty - rename all new movies. Any movie which has been added in the last update data source action will be classified as new.
    • path- rename all movies from the given path(s). You can pass the path(s) via args (multiple, no subpath possible).
    • dataSource- rename all movies from the given data source(s). You can pass the data sources via args (multiple, either index of the data source or the path itself).
    • all- rename all movies.

Export to template

Export your movies using an export template.

Example JSON:

{
  "action": "export",
  "scope": { "name": "all" },
  "args": { "template": "mytemplate", "exportPath": "/tmp/export" }
}
  • action - export
  • scope
    • new or empty - export all new movies. Any movie which has been added in the last update data source action will be classified as new.
    • path- export all movies from the given path(s). You can pass the path(s) via args (multiple, no subpath possible).
    • dataSource- export all movies from the given data source(s). You can pass the data sources via args (multiple, either index of the data source or the path itself).
    • all- export all movies.
  • args
    • template - the template name to use. Needs to be the folder name of the template.
    • exportPath - path where to export your movies to.

TV shows

These actions are executed in the TV show module. To send a command to the TV show module, you need to use the subpath tvshow (e.g. http://localhost:7878/api/tvshow).

Update data sources

Trigger the update data source action. This scans your data sources for new TV shows/episodes.

Example JSON:

{
  "action": "update",
  "scope": { "name": "all" }
}
  • action - update
  • scope
    • all- update all data sources.
    • single- update a single data source. The indices for identifying the data source(s) will be used from args (multiple, starting with 0 for the first data source in your settings).
    • show - update only the given TV show. You need to pass the full path to the TV show(s) to be updated in args (multiple possible).

Reload media info

v5.0.10 Trigger the reload media info action. This reloads media info of all your media files (respecting mediainfo.xml files).

Example JSON:

{
  "action": "reloadMediaInfo",
  "scope": { "name": "all" }
}
  • action - reloadMediaInfo
  • scope
    • new or empty - scrape all new TV shows/episodes. All TV shows/episodes which have been added in the last update data source action will be classified as new.
    • path- scrape all TV shows/episodes from the given path(s). You can pass the path(s) via args (multiple, no subpath possible).
    • dataSource- scrape all TV shows/episodes from the given data source(s). You can pass the data sources via args (multiple, either index of the data source or the path itself).
    • unscraped - scrape all TV shows/episodes which are not scraped
    • all- scrape all TV shows/episodes.

Detect aspect ratio

v5.0.10 Trigger the detect aspect ratio action. This command will run the aspect ratio detector (using FFmpeg) for your episodes.

Example JSON:

{
  "action": "detectAspectRatio",
  "scope": { "name": "all" }
}
  • action - detectAspectRatio
  • scope
    • new or empty - scrape all new TV shows/episodes. All TV shows/episodes which have been added in the last update data source action will be classified as new.
    • path- scrape all TV shows/episodes from the given path(s). You can pass the path(s) via args (multiple, no subpath possible).
    • dataSource- scrape all TV shows/episodes from the given data source(s). You can pass the data sources via args (multiple, either index of the data source or the path itself).
    • unscraped - scrape all TV shows/episodes which are not scraped
    • all- scrape all TV shows/episodes.

Scrape

Scrape your TV shows/episodes from online sources.

Example JSON:

{
  "action": "scrape",
  "scope": { "name": "new" }
}
  • action - scrape
  • scope
    • new or empty - scrape all new TV shows/episodes. All TV shows/episodes which have been added in the update data source action of the current API call will be classified as new.
    • path- scrape all TV shows/episodes from the given path(s). You can pass the path(s) via args (multiple, no subpath possible).
    • dataSource- scrape all TV shows/episodes from the given data source(s). You can pass the data sources via args (multiple, either index of the data source or the path itself).
    • unscraped - scrape all TV shows/episodes which are not scraped
    • all- scrape all TV shows/episodes.

Fetch ratings

Fetch ratings for your TV shows / episodes

Example JSON:

{
  "action": "fetchRatings",
  "scope": { "name": "all" }
}
  • action - fetchRatings
  • scope
    • new or empty - fetch ratings for all new TV shows/episodes. All TV shows/episodes which have been added in the last update data source action will be classified as new.
    • path- fetch ratings for all TV shows/episodes from the given path(s). You can pass the path(s) via args (multiple, no subpath possible).
    • dataSource- scrape all TV shows/episodes from the given data source(s). You can pass the data sources via args (multiple, either index of the data source or the path itself).
    • unscraped - fetch ratings for all TV shows/episodes which are not scraped
    • all- fetch ratings for all TV shows/episodes.

    Trailer download

Download trailers.

Example JSON:

{
  "action": "downloadTrailer",
  "scope": { "name": "all" },
  "args": { "onlyMissing": true }
}
  • action - downloadTrailer
  • scope
    • new or empty - download trailers for all new TV shows. All TV shows which have been added in the last update data source action will be classified as new.
    • path- download trailers for all TV shows from the given path(s). You can pass the path(s) via args (multiple, no subpath possible).
    • dataSource- download trailers for all TV shows from the given data source(s). You can pass the data sources via args (multiple, either index of the data source or the path itself).
    • all- download trailers for all TV shows.
  • args
    • onlyMissing (true/false) - only download missing trailers (optional, defaults to true if omitted).

Subtitle download

Download subtitles.

Example JSON:

{
  "action": "downloadSubtitle",
  "scope": { "name": "all" },
  "args": { "language": "en", "onlyMissing": true }
}
  • action - downloadSubtitle
  • scope
    • new or empty - download subtitles for all new episodes. All episodes which have been added in the last update data source action will be classified as new.
    • path- download subtitles for all episodes from the given TV show path(s). You can pass the path(s) via args (multiple, no subpath possible).
    • dataSource- download subtitles for all episodes from the given data source(s). You can pass the data sources via args (multiple, either index of the data source or the path itself).
    • all- download subtitles for all episodes.
  • args
    • language (ISO code) - the language to download the subtitles for (optional, defaults to the language of the settings if omitted).
    • onlyMissing (true/false) - only download missing subtitles (optional, defaults to true if omitted).

Download missing artwork

Download missing artwork for TV shows/episodes.

Example JSON:

{
  "action": "downloadMissingArtwork",
  "scope": { "name": "all" }
}
  • action - downloadMissingArtwork
  • scope
    • new or empty - fetch ratings for all new TV shows/episodes. All TV shows/episodes which have been added in the last update data source action will be classified as new.
    • path- fetch ratings for all TV shows/episodes from the given path(s). You can pass the path(s) via args (multiple, no subpath possible).
    • dataSource- scrape all TV shows/episodes from the given data source(s). You can pass the data sources via args (multiple, either index of the data source or the path itself).
    • unscraped - fetch ratings for all TV shows/episodes which are not scraped
    • all- fetch ratings for all TV shows/episodes.

Rename

Rename your TV shows/episodes according to your renamer patterns.

Example JSON:

{
  "action": "rename",
  "scope": { "name": "all" }
}
  • action - rename
  • scope
    • new or empty - rename all new TV shows/episodes. All TV shows/episodes which have been added in the last update data source action will be classified as new.
    • path- rename all TV shows/episodes from the given path(s). You can pass the path(s) via args (multiple, no subpath possible).
    • dataSource- rename all TV shows/episodes from the given data source(s). You can pass the data sources via args (multiple, either index of the data source or the path itself).
    • all- rename all TV shows/episodes.

Export to template

Export your TV shows using an export template.

Example JSON:

{
  "action": "export",
  "scope": { "name": "all" },
  "args": { "template": "mytemplate", "exportPath": "/tmp/export" }
}
  • action - export
  • scope
    • new or empty - export all new TV shows. All TV shows which has been added in the last update data source action will be classified as new.
    • path- export all TV shows from the given path(s). You can pass the path(s) via args (multiple, no subpath possible).
    • dataSource- export all TV shows from the given data source(s). You can pass the data sources via args (multiple, either index of the data source or the path itself).
    • all- export all TV shows.
  • args
    • template - the template name to use. Needs to be the folder name of the template.
    • exportPath - path where to export your movies to.

Examples

Update all movie data sources

curl -d '{"action":"update", "scope":{"name":"all"}}' \
  -H "Content-Type: application/json" \
  -H "api-key: <your-api-key>" \
  -X POST http://localhost:7878/api/movie

Update all TV show data sources AND scrape the new items

curl -d '[{"action":"update", "scope":{"name":"all"}}, {"action":"scrape", "scope":{"name":"new"}}]' \
  -H "Content-Type: application/json" \
  -H "api-key: <your-api-key>" \
  -X POST http://localhost:7878/api/tvshow

Fetch subtitles for movies from the first data source (in French)

curl -d '{"action":"downloadSubtitle", "scope":{"name":"dataSource", "args":[0]}, "args":{"language":"fr"}}' \
  -H "Content-Type: application/json" \
  -H "api-key: <your-api-key>" \
  -X POST http://localhost:7878/api/movie

Fetch ratings for all movies

curl -d '[{"action":"fetchRatings", "scope":{"name":"all"}}]' \
  -H "Content-Type: application/json" \
  -H "api-key: <your-api-key>" \
  -X POST http://localhost:7878/api/movie

More complex scenarios

1. Update all movie data sources, then scrape new movies with a specific scraper, and download missing artwork for those new movies

curl -d '[
  {"action": "update", "scope": {"name": "all"}},
  {"action": "scrape", "scope": {"name": "new"}, "args": {"scraper": "tmdb"}},
  {"action": "downloadMissingArtwork", "scope": {"name": "new"}}
]' \
  -H "Content-Type: application/json" \
  -H "api-key: <your-api-key>" \
  -X POST http://localhost:7878/api/movie

2. Scrape all TV shows from a specific data source (by path), fetch ratings, and download English subtitles for all episodes

curl -d '[
  {"action": "scrape", "scope": {"name": "dataSource", "args": "/media/tv_shows/HD"}},
  {"action": "fetchRatings", "scope": {"name": "all"}},
  {"action": "downloadSubtitle", "scope": {"name": "all"}, "args": {"language": "en"}}
]' \
  -H "Content-Type: application/json" \
  -H "api-key: <your-api-key>" \
  -X POST http://localhost:7878/api/tvshow

3. Update alldata sources, scrape & rename all new movies and export them using a custom template

curl -d '[
  {"action": "update", "scope": {"name": "all"}},
  {"action": "scrape", "scope": {"name": "new"}},
  {"action": "rename", "scope": {"name": "new"}},
  {"action": "export", "scope": {"name": "new"}, "args": {"template": "custom", "exportPath": "/tmp/new_export"}}
]' \
  -H "Content-Type: application/json" \
  -H "api-key: <your-api-key>" \
  -X POST http://localhost:7878/api/movie

4. Download missing trailers and subtitles (in German) for all TV shows from a specific path

curl -d '[
  {"action": "downloadTrailer", "scope": {"name": "path", "args": ["/media/tvshows"]}, "args": {"onlyMissing": true}},
  {"action": "downloadSubtitle", "scope": {"name": "path", "args": ["/media/tvshows"]}, "args": {"language": "de", "onlyMissing": true}}
]' \
  -H "Content-Type: application/json" \
  -H "api-key: <your-api-key>" \
  -X POST http://localhost:7878/api/tvshow

5. Update a single movie data source (by index), scrape, and fetch ratings for only new movies

curl -d '[
  {"action": "update", "scope": {"name": "single", "args": [0]}},
  {"action": "scrape", "scope": {"name": "new"}},
  {"action": "fetchRatings", "scope": {"name": "new"}}
]' \
  -H "Content-Type: application/json" \
  -H "api-key: <your-api-key>" \
  -X POST http://localhost:7878/api/movie