# API Reference The API is still pretty new and needs some serious cleaning up on the backend but should be reasonably functional. There are no error codes yet. ## General structure The API endpoint is `http://ip:port + HTTP_ROOT + /api/v2?apikey=$apikey&cmd=$command` Response example (default `json`) ``` { "response": { "data": [ { "loglevel": "INFO", "msg": "Signal 2 caught, saving and exiting...", "thread": "MainThread", "time": "22-sep-2015 01:42:56 " } ], "message": null, "result": "success" } } ``` ``` General optional parameters: out_type: "json" or "xml" callback: "pong" debug: 1 ``` ## API methods ### arnold Get to the chopper! ### backup_config Create a manual backup of the `config.ini` file. ### backup_db Create a manual backup of the `plexpy.db` file. ### delete_all_library_history Delete all PlexPy history for a specific library. ``` Required parameters: section_id (str): The id of the Plex library section Optional parameters: None Returns: None ``` ### delete_all_user_history Delete all PlexPy history for a specific user. ``` Required parameters: user_id (str): The id of the Plex user Optional parameters: None Returns: None ``` ### delete_cache Delete and recreate the cache directory. ### delete_datatable_media_info_cache Delete the media info table cache for a specific library. ``` Required parameters: section_id (str): The id of the Plex library section Optional parameters: None Returns: None ``` ### delete_image_cache Delete and recreate the image cache directory. ### delete_library Delete a library section from PlexPy. Also erases all history for the library. ``` Required parameters: section_id (str): The id of the Plex library section Optional parameters: None Returns: None ``` ### delete_login_log Delete the PlexPy login logs. ``` Required paramters: None Optional parameters: None Returns: None ``` ### delete_notification_log Delete the PlexPy notification logs. ``` Required paramters: None Optional parameters: None Returns: None ``` ### delete_temp_sessions Flush out all of the temporary sessions in the database. ### delete_user Delete a user from PlexPy. Also erases all history for the user. ``` Required parameters: user_id (str): The id of the Plex user Optional parameters: None Returns: None ``` ### docs Return the api docs as a dict where commands are keys, docstring are value. ### docs_md Return the api docs formatted with markdown. ### download_log Download the PlexPy log file. ### download_plex_log Download the Plex log file. ### edit_library Update a library section on PlexPy. ``` Required parameters: section_id (str): The id of the Plex library section Optional parameters: custom_thumb (str): The URL for the custom library thumbnail do_notify (int): 0 or 1 do_notify_created (int): 0 or 1 keep_history (int): 0 or 1 Returns: None ``` ### edit_user Update a user on PlexPy. ``` Required parameters: user_id (str): The id of the Plex user Optional paramters: friendly_name(str): The friendly name of the user custom_thumb (str): The URL for the custom user thumbnail do_notify (int): 0 or 1 do_notify_created (int): 0 or 1 keep_history (int): 0 or 1 Returns: None ``` ### get_activity Get the current activity on the PMS. ``` Required parameters: None Optional parameters: None Returns: json: {"stream_count": 3, "session": [{"art": "/library/metadata/1219/art/1462175063", "aspect_ratio": "1.78", "audio_channels": "6", "audio_codec": "ac3", "audio_decision": "transcode", "bif_thumb": "/library/parts/274169/indexes/sd/", "bitrate": "10617", "container": "mkv", "content_rating": "TV-MA", "duration": "2998290", "friendly_name": "Mother of Dragons", "grandparent_rating_key": "1219", "grandparent_thumb": "/library/metadata/1219/thumb/1462175063", "grandparent_title": "Game of Thrones", "height": "1078", "indexes": 1, "ip_address": "xxx.xxx.xxx.xxx", "labels": [], "machine_id": "83f189w617623ccs6a1lqpby", "media_index": "1", "media_type": "episode", "parent_media_index": "6", "parent_rating_key": "153036", "parent_thumb": "/library/metadata/153036/thumb/1462175062", "parent_title": "", "platform": "Chrome", "player": "Plex Web (Chrome)", "progress_percent": "0", "rating_key": "153037", "section_id": "2", "session_key": "291", "state": "playing", "throttled": "1", "thumb": "/library/metadata/153037/thumb/1462175060", "title": "The Red Woman", "transcode_audio_channels": "2", "transcode_audio_codec": "aac", "transcode_container": "mkv", "transcode_height": "1078", "transcode_key": "tiv5p524wcupe8nxegc26s9k9", "transcode_progress": 2, "transcode_protocol": "http", "transcode_speed": "0.0", "transcode_video_codec": "h264", "transcode_width": "1920", "user": "DanyKhaleesi69", "user_id": 8008135, "user_thumb": "https://plex.tv/users/568gwwoib5t98a3a/avatar", "video_codec": "h264", "video_decision": "copy", "video_framerate": "24p", "video_resolution": "1080", "view_offset": "", "width": "1920", "year": "2016" }, {...}, {...} ] } ``` ### get_apikey Get the apikey. Username and password are required if auth is enabled. Makes and saves the apikey if it does not exist. ``` Required parameters: None Optional parameters: username (str): Your PlexPy username password (str): Your PlexPy password Returns: string: "apikey" ``` ### get_date_formats Get the date and time formats used by PlexPy. ``` Required parameters: None Optional parameters: None Returns: json: {"date_format": "YYYY-MM-DD", "time_format": "HH:mm", } ``` ### get_geoip_lookup Get the geolocation info for an IP address. The GeoLite2 database must be installed. ``` Required parameters: ip_address Optional parameters: None Returns: json: {"continent": "North America", "country": "United States", "region": "California", "city": "Mountain View", "postal_code": "94035", "timezone": "America/Los_Angeles", "latitude": 37.386, "longitude": -122.0838, "accuracy": 1000 } json: {"error": "The address 127.0.0.1 is not in the database." } ``` ### get_history Get the PlexPy history. ``` Required parameters: None Optional parameters: grouping (int): 0 or 1 user (str): "Jon Snow" user_id (int): 133788 rating_key (int): 4348 parent_rating_key (int): 544 grandparent_rating_key (int): 351 start_date (str): "YYYY-MM-DD" section_id (int): 2 media_type (str): "movie", "episode", "track" transcode_decision (str): "direct play", "copy", "transcode", order_column (str): "date", "friendly_name", "ip_address", "platform", "player", "full_title", "started", "paused_counter", "stopped", "duration" order_dir (str): "desc" or "asc" start (int): Row to start from, 0 length (int): Number of items to return, 25 search (str): A string to search for, "Thrones" Returns: json: {"draw": 1, "recordsTotal": 1000, "recordsFiltered": 250, "total_duration": "42 days 5 hrs 18 mins", "filter_duration": "10 hrs 12 mins", "data": [{"year": 2016, "paused_counter": 0, "player": "Plex Web (Chrome)", "parent_rating_key": 544, "parent_title": "", "duration": 263, "transcode_decision": "transcode", "rating_key": 4348, "user_id": 8008135, "thumb": "/library/metadata/4348/thumb/1462414561", "id": 1124, "platform": "Chrome", "media_type": "episode", "grandparent_rating_key": 351, "started": 1462688107, "full_title": "Game of Thrones - The Red Woman", "reference_id": 1123, "date": 1462687607, "percent_complete": 84, "ip_address": "xxx.xxx.xxx.xxx", "group_ids": "1124", "media_index": 17, "friendly_name": "Mother of Dragons", "watched_status": 0, "group_count": 1, "stopped": 1462688370, "parent_media_index": 7, "user": "DanyKhaleesi69" }, {...}, {...} ] } ``` ### get_home_stats Get the homepage watch statistics. ``` Required parameters: None Optional parameters: grouping (int): 0 or 1 time_range (str): The time range to calculate statistics, '30' stats_type (int): 0 for plays, 1 for duration stats_count (str): The number of top items to list, '5' Returns: json: [{"stat_id": "top_movies", "stat_type": "total_plays", "rows": [{...}] }, {"stat_id": "popular_movies", "rows": [{...}] }, {"stat_id": "top_tv", "stat_type": "total_plays", "rows": [{"content_rating": "TV-MA", "friendly_name": "", "grandparent_thumb": "/library/metadata/1219/thumb/1462175063", "labels": [], "last_play": 1462380698, "media_type": "episode", "platform": "", "platform_type": "", "rating_key": 1219, "row_id": 1116, "section_id": 2, "thumb": "", "title": "Game of Thrones", "total_duration": 213302, "total_plays": 69, "user": "", "users_watched": "" }, {...}, {...} ] }, {"stat_id": "popular_tv", "rows": [{...}] }, {"stat_id": "top_music", "stat_type": "total_plays", "rows": [{...}] }, {"stat_id": "popular_music", "rows": [{...}] }, {"stat_id": "last_watched", "rows": [{...}] }, {"stat_id": "top_users", "stat_type": "total_plays", "rows": [{...}] }, {"stat_id": "top_platforms", "stat_type": "total_plays", "rows": [{...}] }, {"stat_id": "most_concurrent", "rows": [{...}] } ] ``` ### get_libraries Get a list of all libraries on your server. ``` Required parameters: None Optional parameters: None Returns: json: [{"art": "/:/resources/show-fanart.jpg", "child_count": "3745", "count": "62", "parent_count": "240", "section_id": "2", "section_name": "TV Shows", "section_type": "show", "thumb": "/:/resources/show.png" }, {...}, {...} ] ``` ### get_libraries_table Get the data on the PlexPy libraries table. ``` Required parameters: None Optional parameters: order_column (str): "library_thumb", "section_name", "section_type", "count", "parent_count", "child_count", "last_accessed", "last_played", "plays", "duration" order_dir (str): "desc" or "asc" start (int): Row to start from, 0 length (int): Number of items to return, 25 search (str): A string to search for, "Movies" Returns: json: {"draw": 1, "recordsTotal": 10, "recordsFiltered": 10, "data": [{"child_count": 3745, "content_rating": "TV-MA", "count": 62, "do_notify": "Checked", "do_notify_created": "Checked", "duration": 1578037, "id": 1128, "keep_history": "Checked", "labels": [], "last_accessed": 1462693216, "last_played": "Game of Thrones - The Red Woman", "library_art": "/:/resources/show-fanart.jpg", "library_thumb": "", "media_index": 1, "media_type": "episode", "parent_count": 240, "parent_media_index": 6, "parent_title": "", "plays": 772, "rating_key": 153037, "section_id": 2, "section_name": "TV Shows", "section_type": "Show", "thumb": "/library/metadata/153036/thumb/1462175062", "year": 2016 }, {...}, {...} ] } ``` ### get_library Get a library's details. ``` Required parameters: section_id (str): The id of the Plex library section Optional parameters: None Returns: json: {"child_count": null, "count": 887, "do_notify": 1, "do_notify_created": 1, "keep_history": 1, "library_art": "/:/resources/movie-fanart.jpg", "library_thumb": "/:/resources/movie.png", "parent_count": null, "section_id": 1, "section_name": "Movies", "section_type": "movie" } ``` ### get_library_media_info Get the data on the PlexPy media info tables. ``` Required parameters: section_id (str): The id of the Plex library section, OR rating_key (str): The grandparent or parent rating key Optional parameters: section_type (str): "movie", "show", "artist", "photo" order_column (str): "added_at", "title", "container", "bitrate", "video_codec", "video_resolution", "video_framerate", "audio_codec", "audio_channels", "file_size", "last_played", "play_count" order_dir (str): "desc" or "asc" start (int): Row to start from, 0 length (int): Number of items to return, 25 search (str): A string to search for, "Thrones" Returns: json: {"draw": 1, "recordsTotal": 82, "recordsFiltered": 82, "filtered_file_size": 2616760056742, "total_file_size": 2616760056742, "data": [{"added_at": "1403553078", "audio_channels": "", "audio_codec": "", "bitrate": "", "container": "", "file_size": 253660175293, "grandparent_rating_key": "", "last_played": 1462380698, "media_index": "1", "media_type": "show", "parent_media_index": "", "parent_rating_key": "", "play_count": 15, "rating_key": "1219", "section_id": 2, "section_type": "show", "thumb": "/library/metadata/1219/thumb/1436265995", "title": "Game of Thrones", "video_codec": "", "video_framerate": "", "video_resolution": "", "year": "2011" }, {...}, {...} ] } ``` ### get_library_names Get a list of library sections and ids on the PMS. ``` Required parameters: None Optional parameters: None Returns: json: [{"section_id": 1, "section_name": "Movies"}, {"section_id": 7, "section_name": "Music"}, {"section_id": 2, "section_name": "TV Shows"}, {...} ] ``` ### get_library_user_stats Get a library's user statistics. ``` Required parameters: section_id (str): The id of the Plex library section Optional parameters: None Returns: json: [{"friendly_name": "Jon Snow", "total_plays": 170, "user_id": 133788, "user_thumb": "https://plex.tv/users/k10w42309cynaopq/avatar" }, {"platform_type": "DanyKhaleesi69", "total_plays": 42, "user_id": 8008135, "user_thumb": "https://plex.tv/users/568gwwoib5t98a3a/avatar" }, {...}, {...} ] ``` ### get_library_watch_time_stats Get a library's watch time statistics. ``` Required parameters: section_id (str): The id of the Plex library section Optional parameters: None Returns: json: [{"query_days": 1, "total_plays": 0, "total_time": 0 }, {"query_days": 7, "total_plays": 3, "total_time": 15694 }, {"query_days": 30, "total_plays": 35, "total_time": 63054 }, {"query_days": 0, "total_plays": 508, "total_time": 1183080 } ] ``` ### get_logs Get the PlexPy logs. ``` Required parameters: None Optional parameters: sort (str): "time", "thread", "msg", "loglevel" search (str): A string to search for order (str): "desc" or "asc" regex (str): A regex string to search for start (int): Row number to start from end (int): Row number to end at Returns: json: [{"loglevel": "DEBUG", "msg": "Latest version is 2d10b0748c7fa2ee4cf59960c3d3fffc6aa9512b", "thread": "MainThread", "time": "2016-05-08 09:36:51 " }, {...}, {...} ] ``` ### get_metadata Get the metadata for a media item. ``` Required parameters: rating_key (str): Rating key of the item media_info (bool): True or False whether to get media info Optional parameters: None Returns: json: {"metadata": {"actors": [ "Kit Harington", "Emilia Clarke", "Isaac Hempstead-Wright", "Maisie Williams", "Liam Cunningham", ], "added_at": "1461572396", "art": "/library/metadata/1219/art/1462175063", "content_rating": "TV-MA", "directors": [ "Jeremy Podeswa" ], "duration": "2998290", "genres": [ "Adventure", "Drama", "Fantasy" ], "grandparent_rating_key": "1219", "grandparent_thumb": "/library/metadata/1219/thumb/1462175063", "grandparent_title": "Game of Thrones", "guid": "com.plexapp.agents.thetvdb://121361/6/1?lang=en", "labels": [], "last_viewed_at": "1462165717", "library_name": "TV Shows", "media_index": "1", "media_type": "episode", "originally_available_at": "2016-04-24", "parent_media_index": "6", "parent_rating_key": "153036", "parent_thumb": "/library/metadata/153036/thumb/1462175062", "parent_title": "", "rating": "7.8", "rating_key": "153037", "section_id": "2", "studio": "HBO", "summary": "Jon Snow is dead. Daenerys meets a strong man. Cersei sees her daughter again.", "tagline": "", "thumb": "/library/metadata/153037/thumb/1462175060", "title": "The Red Woman", "updated_at": "1462175060", "writers": [ "David Benioff", "D. B. Weiss" ], "year": "2016" } } ``` ### get_new_rating_keys Get a list of new rating keys for the PMS of all of the item's parent/children. ``` Required parameters: rating_key (str): '12345' media_type (str): "movie", "show", "season", "episode", "artist", "album", "track" Optional parameters: None Returns: json: {} ``` ### get_notification_log Get the data on the PlexPy notification logs table. ``` Required parameters: None Optional parameters: order_column (str): "timestamp", "agent_name", "notify_action", "subject_text", "body_text", "script_args" order_dir (str): "desc" or "asc" start (int): Row to start from, 0 length (int): Number of items to return, 25 search (str): A string to search for, "Telegram" Returns: json: {"draw": 1, "recordsTotal": 1039, "recordsFiltered": 163, "data": [{"agent_id": 13, "agent_name": "Telegram", "body_text": "Game of Thrones - S06E01 - The Red Woman [Transcode].", "id": 1000, "notify_action": "play", "poster_url": "http://i.imgur.com/ZSqS8Ri.jpg", "rating_key": 153037, "script_args": "[]", "session_key": 147, "subject_text": "PlexPy (Winterfell-Server)", "timestamp": 1462253821, "user": "DanyKhaleesi69", "user_id": 8008135 }, {...}, {...} ] } ``` ### get_old_rating_keys Get a list of old rating keys from the PlexPy database for all of the item's parent/children. ``` Required parameters: rating_key (str): '12345' media_type (str): "movie", "show", "season", "episode", "artist", "album", "track" Optional parameters: None Returns: json: {} ``` ### get_plays_by_date Get graph data by date. ``` Required parameters: None Optional parameters: time_range (str): The number of days of data to return y_axis (str): "plays" or "duration" user_id (str): The user id to filter the data Returns: json: {"categories": ["YYYY-MM-DD", "YYYY-MM-DD", ...] "series": [{"name": "Movies", "data": [...]} {"name": "TV", "data": [...]}, {"name": "Music", "data": [...]} ] } ``` ### get_plays_by_dayofweek Get graph data by day of the week. ``` Required parameters: None Optional parameters: time_range (str): The number of days of data to return y_axis (str): "plays" or "duration" user_id (str): The user id to filter the data Returns: json: {"categories": ["Sunday", "Monday", "Tuesday", ..., "Saturday"] "series": [{"name": "Movies", "data": [...]} {"name": "TV", "data": [...]}, {"name": "Music", "data": [...]} ] } ``` ### get_plays_by_hourofday Get graph data by hour of the day. ``` Required parameters: None Optional parameters: time_range (str): The number of days of data to return y_axis (str): "plays" or "duration" user_id (str): The user id to filter the data Returns: json: {"categories": ["00", "01", "02", ..., "23"] "series": [{"name": "Movies", "data": [...]} {"name": "TV", "data": [...]}, {"name": "Music", "data": [...]} ] } ``` ### get_plays_by_source_resolution Get graph data by source resolution. ``` Required parameters: None Optional parameters: time_range (str): The number of days of data to return y_axis (str): "plays" or "duration" user_id (str): The user id to filter the data Returns: json: {"categories": ["720", "1080", "sd", ...] "series": [{"name": "Direct Play", "data": [...]} {"name": "Direct Stream", "data": [...]}, {"name": "Transcode", "data": [...]} ] } ``` ### get_plays_by_stream_resolution Get graph data by stream resolution. ``` Required parameters: None Optional parameters: time_range (str): The number of days of data to return y_axis (str): "plays" or "duration" user_id (str): The user id to filter the data Returns: json: {"categories": ["720", "1080", "sd", ...] "series": [{"name": "Direct Play", "data": [...]} {"name": "Direct Stream", "data": [...]}, {"name": "Transcode", "data": [...]} ] } ``` ### get_plays_by_stream_type Get graph data by stream type by date. ``` Required parameters: None Optional parameters: time_range (str): The number of days of data to return y_axis (str): "plays" or "duration" user_id (str): The user id to filter the data Returns: json: {"categories": ["YYYY-MM-DD", "YYYY-MM-DD", ...] "series": [{"name": "Direct Play", "data": [...]} {"name": "Direct Stream", "data": [...]}, {"name": "Transcode", "data": [...]} ] } ``` ### get_plays_by_top_10_platforms Get graph data by top 10 platforms. ``` Required parameters: None Optional parameters: time_range (str): The number of days of data to return y_axis (str): "plays" or "duration" user_id (str): The user id to filter the data Returns: json: {"categories": ["iOS", "Android", "Chrome", ...] "series": [{"name": "Movies", "data": [...]} {"name": "TV", "data": [...]}, {"name": "Music", "data": [...]} ] } ``` ### get_plays_by_top_10_users Get graph data by top 10 users. ``` Required parameters: None Optional parameters: time_range (str): The number of days of data to return y_axis (str): "plays" or "duration" user_id (str): The user id to filter the data Returns: json: {"categories": ["Jon Snow", "DanyKhaleesi69", "A Girl", ...] "series": [{"name": "Movies", "data": [...]} {"name": "TV", "data": [...]}, {"name": "Music", "data": [...]} ] } ``` ### get_plays_per_month Get graph data by month. ``` Required parameters: None Optional parameters: time_range (str): The number of days of data to return y_axis (str): "plays" or "duration" user_id (str): The user id to filter the data Returns: json: {"categories": ["Jan 2016", "Feb 2016", "Mar 2016", ...] "series": [{"name": "Movies", "data": [...]} {"name": "TV", "data": [...]}, {"name": "Music", "data": [...]} ] } ``` ### get_plex_log Get the PMS logs. ``` Required parameters: None Optional parameters: window (int): The number of tail lines to return log_type (str): "server" or "scanner" Returns: json: [["May 08, 2016 09:35:37", "DEBUG", "Auth: Came in with a super-token, authorization succeeded." ], [...], [...] ] ``` ### get_pms_token Get the user's Plex token used for PlexPy. ``` Required parameters: username (str): The Plex.tv username password (str): The Plex.tv password Optional parameters: None Returns: string: The Plex token used for PlexPy ``` ### get_recently_added Get all items that where recelty added to plex. ``` Required parameters: count (str): Number of items to return Optional parameters: start (str): The item number to start at section_id (str): The id of the Plex library section Returns: json: {"recently_added": [{"added_at": "1461572396", "grandparent_rating_key": "1219", "grandparent_thumb": "/library/metadata/1219/thumb/1462175063", "grandparent_title": "Game of Thrones", "library_name": "", "media_index": "1", "media_type": "episode", "parent_media_index": "6", "parent_rating_key": "153036", "parent_thumb": "/library/metadata/153036/thumb/1462175062", "parent_title": "", "rating_key": "153037", "section_id": "2", "thumb": "/library/metadata/153037/thumb/1462175060", "title": "The Red Woman", "year": "2016" }, {...}, {...} ] } ``` ### get_server_friendly_name Get the name of the PMS. ``` Required parameters: None Optional parameters: None Returns: string: "Winterfell-Server" ``` ### get_server_id Get the PMS server identifier. ``` Required parameters: hostname (str): 'localhost' or '192.160.0.10' port (int): 32400 Optional parameters: ssl (int): 0 or 1 remote (int): 0 or 1 Returns: string: The unique PMS identifier ``` ### get_server_identity Get info about the local server. ``` Required parameters: None Optional parameters: None Returns: json: [{"machine_identifier": "ds48g4r354a8v9byrrtr697g3g79w", "version": "0.9.15.x.xxx-xxxxxxx" } ] ``` ### get_server_list Get all your servers that are published to Plex.tv. ``` Required parameters: None Optional parameters: None Returns: json: [{"clientIdentifier": "ds48g4r354a8v9byrrtr697g3g79w", "httpsRequired": "0", "ip": "xxx.xxx.xxx.xxx", "label": "Winterfell-Server", "local": "1", "port": "32400", "value": "xxx.xxx.xxx.xxx" }, {...}, {...} ] ``` ### get_server_pref Get a specified PMS server preference. ``` Required parameters: pref (str): Name of preference Returns: string: Value of preference ``` ### get_servers_info Get info about the PMS. ``` Required parameters: None Optional parameters: None Returns: json: [{"port": "32400", "host": "10.0.0.97", "version": "0.9.15.2.1663-7efd046", "name": "Winterfell-Server", "machine_identifier": "ds48g4r354a8v9byrrtr697g3g79w" } ] ``` ### get_settings Gets all settings from the config file. ``` Required parameters: None Optional parameters: key (str): Name of a config section to return Returns: json: {"General": {"api_enabled": true, ...} "Advanced": {"cache_sizemb": "32", ...}, ... } ``` ### get_stream_type_by_top_10_platforms Get graph data by stream type by top 10 platforms. ``` Required parameters: None Optional parameters: time_range (str): The number of days of data to return y_axis (str): "plays" or "duration" user_id (str): The user id to filter the data Returns: json: {"categories": ["iOS", "Android", "Chrome", ...] "series": [{"name": "Direct Play", "data": [...]} {"name": "Direct Stream", "data": [...]}, {"name": "Transcode", "data": [...]} ] } ``` ### get_stream_type_by_top_10_users Get graph data by stream type by top 10 users. ``` Required parameters: None Optional parameters: time_range (str): The number of days of data to return y_axis (str): "plays" or "duration" user_id (str): The user id to filter the data Returns: json: {"categories": ["Jon Snow", "DanyKhaleesi69", "A Girl", ...] "series": [{"name": "Direct Play", "data": [...]} {"name": "Direct Stream", "data": [...]}, {"name": "Transcode", "data": [...]} ] } ``` ### get_synced_items Get a list of synced items on the PMS. ``` Required parameters: machine_id (str): The PMS identifier Optional parameters: user_id (str): The id of the Plex user Returns: json: [{"content_type": "video", "device_name": "Tyrion's iPad", "failure": "", "friendly_name": "Tyrion Lannister", "item_complete_count": "0", "item_count": "1", "item_downloaded_count": "0", "item_downloaded_percent_complete": 0, "metadata_type": "movie", "music_bitrate": "192", "photo_quality": "74", "platform": "iOS", "rating_key": "154092", "root_title": "Deadpool", "state": "pending", "sync_id": "11617019", "title": "Deadpool", "total_size": "0", "user_id": "696969", "username": "DrukenDwarfMan", "video_quality": "60" }, {...}, {...} ] ``` ### get_user Get a user's details. ``` Required parameters: user_id (str): The id of the Plex user Optional parameters: None Returns: json: {"allow_guest": 1, "deleted_user": 0, "do_notify": 1, "email": "Jon.Snow.1337@CastleBlack.com", "friendly_name": "Jon Snow", "is_allow_sync": 1, "is_home_user": 1, "is_restricted": 0, "keep_history": 1, "shared_libraries": ["10", "1", "4", "5", "15", "20", "2"], "user_id": 133788, "user_thumb": "https://plex.tv/users/k10w42309cynaopq/avatar", "username": "LordCommanderSnow" } ``` ### get_user_ips Get the data on PlexPy users IP table. ``` Required parameters: user_id (str): The id of the Plex user Optional parameters: order_column (str): "last_seen", "ip_address", "platform", "player", "last_played", "play_count" order_dir (str): "desc" or "asc" start (int): Row to start from, 0 length (int): Number of items to return, 25 search (str): A string to search for, "xxx.xxx.xxx.xxx" Returns: json: {"draw": 1, "recordsTotal": 2344, "recordsFiltered": 10, "data": [{"friendly_name": "Jon Snow", "id": 1121, "ip_address": "xxx.xxx.xxx.xxx", "last_played": "Game of Thrones - The Red Woman", "last_seen": 1462591869, "media_index": 1, "media_type": "episode", "parent_media_index": 6, "parent_title": "", "platform": "Chrome", "play_count": 149, "player": "Plex Web (Chrome)", "rating_key": 153037, "thumb": "/library/metadata/153036/thumb/1462175062", "transcode_decision": "transcode", "user_id": 133788, "year": 2016 }, {...}, {...} ] } ``` ### get_user_logins Get the data on PlexPy user login table. ``` Required parameters: user_id (str): The id of the Plex user Optional parameters: order_column (str): "date", "time", "ip_address", "host", "os", "browser" order_dir (str): "desc" or "asc" start (int): Row to start from, 0 length (int): Number of items to return, 25 search (str): A string to search for, "xxx.xxx.xxx.xxx" Returns: json: {"draw": 1, "recordsTotal": 2344, "recordsFiltered": 10, "data": [{"browser": "Safari 7.0.3", "friendly_name": "Jon Snow", "host": "http://plexpy.castleblack.com", "ip_address": "xxx.xxx.xxx.xxx", "os": "Mac OS X", "timestamp": 1462591869, "user": "LordCommanderSnow", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_3) AppleWebKit/537.75.14 (KHTML, like Gecko) Version/7.0.3 Safari/7046A194A", "user_group": "guest", "user_id": 133788 }, {...}, {...} ] } ``` ### get_user_names Get a list of all user and user ids. ``` Required parameters: None Optional parameters: None Returns: json: [{"friendly_name": "Jon Snow", "user_id": 133788}, {"friendly_name": "DanyKhaleesi69", "user_id": 8008135}, {"friendly_name": "Tyrion Lannister", "user_id": 696969}, {...}, ] ``` ### get_user_player_stats Get a user's player statistics. ``` Required parameters: user_id (str): The id of the Plex user Optional parameters: None Returns: json: [{"platform_type": "Chrome", "player_name": "Plex Web (Chrome)", "result_id": 1, "total_plays": 170 }, {"platform_type": "Chromecast", "player_name": "Chromecast", "result_id": 2, "total_plays": 42 }, {...}, {...} ] ``` ### get_user_watch_time_stats Get a user's watch time statistics. ``` Required parameters: user_id (str): The id of the Plex user Optional parameters: None Returns: json: [{"query_days": 1, "total_plays": 0, "total_time": 0 }, {"query_days": 7, "total_plays": 3, "total_time": 15694 }, {"query_days": 30, "total_plays": 35, "total_time": 63054 }, {"query_days": 0, "total_plays": 508, "total_time": 1183080 } ] ``` ### get_users Get a list of all users that have access to your server. ``` Required parameters: None Optional parameters: None Returns: json: [{"email": "Jon.Snow.1337@CastleBlack.com", "filter_all": "", "filter_movies": "", "filter_music": "", "filter_photos": "", "filter_tv": "", "is_allow_sync": null, "is_home_user": "1", "is_restricted": "0", "thumb": "https://plex.tv/users/k10w42309cynaopq/avatar", "user_id": "133788", "username": "Jon Snow" }, {...}, {...} ] ``` ### get_users_table Get the data on PlexPy users table. ``` Required parameters: None Optional parameters: order_column (str): "user_thumb", "friendly_name", "last_seen", "ip_address", "platform", "player", "last_played", "plays", "duration" order_dir (str): "desc" or "asc" start (int): Row to start from, 0 length (int): Number of items to return, 25 search (str): A string to search for, "Jon Snow" Returns: json: {"draw": 1, "recordsTotal": 10, "recordsFiltered": 10, "data": [{"allow_guest": "Checked", "do_notify": "Checked", "duration": 2998290, "friendly_name": "Jon Snow", "id": 1121, "ip_address": "xxx.xxx.xxx.xxx", "keep_history": "Checked", "last_played": "Game of Thrones - The Red Woman", "last_seen": 1462591869, "media_index": 1, "media_type": "episode", "parent_media_index": 6, "parent_title": "", "platform": "Chrome", "player": "Plex Web (Chrome)", "plays": 487, "rating_key": 153037, "thumb": "/library/metadata/153036/thumb/1462175062", "transcode_decision": "transcode", "user_id": 133788, "user_thumb": "https://plex.tv/users/568gwwoib5t98a3a/avatar", "year": 2016 }, {...}, {...} ] } ``` ### get_whois_lookup Get the connection info for an IP address. ``` Required parameters: ip_address Optional parameters: None Returns: json: {"host": "google-public-dns-a.google.com", "nets": [{"description": "Google Inc.", "address": "1600 Amphitheatre Parkway", "city": "Mountain View", "state": "CA", "postal_code": "94043", "country": "United States", ... }, {...} ] json: {"host": "Not available", "nets": [], "error": "IPv4 address 127.0.0.1 is already defined as Loopback via RFC 1122, Section 3.2.1.3." } ``` ### import_database Import a PlexWatch or Plexivity database into PlexPy. ``` Required parameters: app (str): "plexwatch" or "plexivity" database_path (str): The full path to the plexwatch database file table_name (str): "processed" or "grouped" Optional parameters: import_ignore_interval (int): The minimum number of seconds for a stream to import Returns: None ``` ### install_geoip_db Downloads and installs the GeoLite2 database ### notify Send a notification using PlexPy. ``` Required parameters: agent_id(str): The id of the notification agent to use 9 # Boxcar2 17 # Browser 10 # Email 16 # Facebook 0 # Growl 19 # Hipchat 12 # IFTTT 18 # Join 4 # NotifyMyAndroid 3 # Plex Home Theater 1 # Prowl 5 # Pushalot 6 # Pushbullet 7 # Pushover 15 # Scripts 14 # Slack 13 # Telegram 11 # Twitter 2 # XBMC subject(str): The subject of the message body(str): The body of the message Optional parameters: None Returns: None ``` ### pms_image_proxy Gets an image from the PMS and saves it to the image cache directory. ``` Required parameters: img (str): /library/metadata/153037/thumb/1462175060 or rating_key (str): 54321 Optional parameters: width (str): 150 height (str): 255 fallback (str): "poster", "cover", "art" refresh (bool): True or False whether to refresh the image cache Returns: None ``` ### refresh_libraries_list Refresh the PlexPy libraries list. ### refresh_users_list Refresh the PlexPy users list. ### restart Restart PlexPy. ### search Get search results from the PMS. ``` Required parameters: query (str): The query string to search for Returns: json: {"results_count": 69, "results_list": {"movie": [{...}, {...}, ] }, {"episode": [{...}, {...}, ] }, {...} } ``` ### sql Query the PlexPy database with raw SQL. Automatically makes a backup of the database if the latest backup is older then 24h. `api_sql` must be manually enabled in the config file. ``` Required parameters: query (str): The SQL query Optional parameters: None Returns: None ``` ### undelete_library Restore a deleted library section to PlexPy. ``` Required parameters: section_id (str): The id of the Plex library section section_name (str): The name of the Plex library section Optional parameters: None Returns: None ``` ### undelete_user Restore a deleted user to PlexPy. ``` Required parameters: user_id (str): The id of the Plex user username (str): The username of the Plex user Optional parameters: None Returns: None ``` ### uninstall_geoip_db Uninstalls the GeoLite2 database ### update Check for PlexPy updates on Github. ### update_metadata_details Update the metadata in the PlexPy database by matching rating keys. Also updates all parents or children of the media item if it is a show/season/episode or artist/album/track. ``` Required parameters: old_rating_key (str): 12345 new_rating_key (str): 54321 media_type (str): "movie", "show", "season", "episode", "artist", "album", "track" Optional parameters: None Returns: None ```