API Documentation

Maintenance, back soon

This is a lightweight web service, (REST interface), which provides an easy way to access the YTS website.
An API (Application programming interface) is a protocol intended to be used as an interface by software components to communicate with each other.
Our API supports many methods, so there should not be a problem coding some nice applications.

If you find any bug, or have any questions, or any suggestions please get in touch with us
Contact Us

API Endpoints

All the API endpoints return the same data structure as below

Returned KeyDescriptionExample
statusThe returned status for the API call, can be either 'ok' or 'error'ok
status_messageEither the error message or the successful messageQuery was successful
dataIf 'status' is returned as 'ok' the API query results will be inside 'data'data

List Movies

HTTP GET

EndpointDescription
https://yts.gs/api/v2/list_movies.json
https://yts.gs/api/v2/list_movies.jsonp
https://yts.gs/api/v2/list_movies.xml
Used to list and search through out all the available movies. Can sort, filter, search and order the results

Endpoint Parameters

ParameterRequiredTypeDefaultDescription
limitInteger between 1 - 50 (inclusive)20The limit of results per page that has been set
pageInteger (Unsigned)1Used to see the next page of movies, eg limit=15 and page=2 will show you movies 15-30
qualityString (720p, 1080p, 3D)AllUsed to filter by a given quality
minimum_ratingInteger between 0 - 9 (inclusive)0Used to filter movie by a given minimum IMDb rating
query_termString0Used for movie search, matching on: Movie Title/IMDb Code, Actor Name/IMDb Code, Director Name/IMDb Code
genreStringAllUsed to filter by a given genre (See http://www.imdb.com/genre/ for full list)
sort_byString (title, year, rating, peers, seeds, download_count, like_count, date_added)date_addedSorts the results by choosen value
order_byString (desc, asc)descOrders the results by either Ascending or Descending order
with_rt_ratingsBooleanfalseReturns the list with the Rotten Tomatoes rating included

Examples

URLDescription
https://yts.gs/api/v2/list_movies.json?quality=3DReturns the latest 20 3D movies using JSON format
https://yts.gs/api/v2/list_movies.xml?sort=seeds&limit=15Returns maximum 15 movies which are sorted by seeds

Response Data

Key NameDescriptionExample
movie_countThe total movie count results for your query2131
limitThe limit of results per page that has been set20
page_numberThe current page number you are viewing1
moviesAn array which will hold multiple movies and their relative informationARRAY
To get Magnet URLs you need to construct this yourself like so:

magnet:?xt=urn:btih:TORRENT_HASH&dn=Url+Encoded+Movie+Name&tr=http://track.one:1234/announce&tr=udp://track.two:80

You can add as many trackers as you want, we recommend the following:

- udp://open.demonii.com:1337
- udp://tracker.istole.it:80
- http://tracker.yify-torrents.com/announce
- udp://tracker.publicbt.com:80
- udp://tracker.openbittorrent.com:80
- udp://tracker.coppersurfer.tk:6969
- udp://exodus.desync.com:6969
- http://exodus.desync.com:6969/announce

Movie Details

HTTP GET

EndpointDescription
https://yts.gs/api/v2/movie_details.json
https://yts.gs/api/v2/movie_details.jsonp
https://yts.gs/api/v2/movie_details.xml
Returns the information about a specific movie

Endpoint Parameters

ParameterRequiredTypeDefaultDescription
movie_idInteger (Unsigned)nullThe ID of the movie
with_imagesBooleanfalseWhen set the data returned will include the added image URLs
with_castBooleanfalseWhen set the data returned will include the added information about the cast

Examples

URLDescription
https://yts.gs/api/v2/movie_details.json?movie_id=10Returns basic information about the movie with ID of 10
https://yts.gs/api/v2/movie_details.json?movie_id=15&with_images=true&with_cast=trueReturns the full information (with image urls and cast information) about the movie with ID of 15
To get Magnet URLs you need to construct this yourself like so:

magnet:?xt=urn:btih:TORRENT_HASH&dn=Url+Encoded+Movie+Name&tr=http://track.one:1234/announce&tr=udp://track.two:80

You can add as many trackers as you want, we recommend the following:

- udp://open.demonii.com:1337
- udp://tracker.istole.it:80
- http://tracker.yify-torrents.com/announce
- udp://tracker.publicbt.com:80
- udp://tracker.openbittorrent.com:80
- udp://tracker.coppersurfer.tk:6969
- udp://exodus.desync.com:6969
- http://exodus.desync.com:6969/announce

Movie Suggestions

HTTP GET

EndpointDescription
https://yts.gs/api/v2/movie_suggestions.json
https://yts.gs/api/v2/movie_suggestions.jsonp
https://yts.gs/api/v2/movie_suggestions.xml
Returns 4 related movies as suggestions for the user

Endpoint Parameters

ParameterRequiredTypeDefaultDescription
movie_idInteger (Unsigned)nullThe ID of the movie

Examples

URLDescription
https://yts.gs/api/v2/movie_suggestions.json?movie_id=10Returns related movies to the movie with ID of 10

Movie Comments

HTTP GET

EndpointDescription
https://yts.gs/api/v2/movie_comments.json
https://yts.gs/api/v2/movie_comments.jsonp
https://yts.gs/api/v2/movie_comments.xml
Returns all the comments for the specified movie

Endpoint Parameters

ParameterRequiredTypeDefaultDescription
movie_idInteger (Unsigned)nullThe ID of the movie

Examples

URLDescription
https://yts.gs/api/v2/movie_comments.json?movie_id=10Returns all the comments for the movie with ID of 10

Movie Reviews

HTTP GET

EndpointDescription
https://yts.gs/api/v2/movie_reviews.json
https://yts.gs/api/v2/movie_reviews.jsonp
https://yts.gs/api/v2/movie_reviews.xml
Returns all the IMDb movie reviews for the specified movie

Endpoint Parameters

ParameterRequiredTypeDefaultDescription
movie_idInteger (Unsigned)nullThe ID of the movie

Examples

URLDescription
https://yts.gs/api/v2/movie_reviews.json?movie_id=10Returns IMDb movie reviews for the movie with ID of 10

Movie Parental Guides

HTTP GET

EndpointDescription
https://yts.gs/api/v2/movie_parental_guides.json
https://yts.gs/api/v2/movie_parental_guides.jsonp
https://yts.gs/api/v2/movie_parental_guides.xml
Returns all the parental guide ratings for the specified movie

Endpoint Parameters

ParameterRequiredTypeDefaultDescription
movie_idInteger (Unsigned)nullThe ID of the movie

Examples

URLDescription
https://yts.gs/api/v2/movie_parental_guides.json?movie_id=10Returns the parental guides for the movie with the ID of 10

List Upcoming

HTTP GET

EndpointDescription
https://yts.gs/api/v2/list_upcoming.json
https://yts.gs/api/v2/list_upcoming.jsonp
https://yts.gs/api/v2/list_upcoming.xml
Returns the 4 latest upcoming movies

Examples

URLDescription
https://yts.gs/api/v2/list_upcoming.jsonReturns the 4 latest upcoming movies

User Details

HTTP GET

EndpointDescription
https://yts.gs/api/v2/user_details.json
https://yts.gs/api/v2/user_details.jsonp
https://yts.gs/api/v2/user_details.xml
Get the user details

Endpoint Parameters

ParameterRequiredTypeDefaultDescription
user_idInteger (Unsigned)nullThe ID of the user
with_recently_downloadedBooleannullIf set it will add the most recent downloads by the specified user

Examples

URLDescription
https://yts.gs/api/v2/user_details.json?user_id=16Returns user profile information for the user with the ID of 16

Get User Key

HTTP POST

EndpointDescription
https://yts.gs/api/v2/user_get_key.json
https://yts.gs/api/v2/user_get_key.jsonp
https://yts.gs/api/v2/user_get_key.xml
The same as logging in, if successful the returned data will include the user_key for later use of the API as a means of authentication

Endpoint Parameters

ParameterRequiredTypeDefaultDescription
usernameStringnullThe username of the user you wish to authenticate
passwordStringnullThe password of the user you wish to authenticate
application_keyStringnullTo make any POST requests to our API you must use your developer's 'application_key', if you do not have one please apply HERE

User Profile

HTTP GET

EndpointDescription
https://yts.gs/api/v2/user_profile.json
https://yts.gs/api/v2/user_profile.jsonp
https://yts.gs/api/v2/user_profile.xml
This endpoint will return the full information about an authenticated user

Endpoint Parameters

ParameterRequiredTypeDefaultDescription
user_keyStringnullThe key that you get from authenticating using the API (Get User Key endpoint)

Examples

URLDescription
https://yts.gs/api/v2/user_profile.json?user_key=1e2b2baddff6234Returns the full information about an authenticated user

Edit User Settings

HTTP POST

EndpointDescription
https://yts.gs/api/v2/user_edit_settings.json
https://yts.gs/api/v2/user_edit_settings.jsonp
https://yts.gs/api/v2/user_edit_settings.xml
Endpoint is used to edit an authenticated user's profile settings

Endpoint Parameters

ParameterRequiredTypeDefaultDescription
user_keyStringnullThe key that you get from authenticating using the API (Get User Key endpoint)
application_keyStringnullTo make any POST requests to our API you must use your developer's 'application_key', if you do not have one please apply HERE
new_passwordStringnullThe new desired password
about_textStringnullText describing the user in a short paragraph
avatar_imageimg, jpg, jpeg, gif, png (10MB max)nullUpload (using multi-part) a new avatar image

Register User

HTTP POST

EndpointDescription
https://yts.gs/api/v2/user_register.json
https://yts.gs/api/v2/user_register.jsonp
https://yts.gs/api/v2/user_register.xml
Endpoint is used register a new user

Endpoint Parameters

ParameterRequiredTypeDefaultDescription
application_keyStringnullTo make any POST requests to our API you must use your developer's 'application_key', if you do not have one please apply HERE
usernameStringnullThe desired username
passwordStringnullThe desired password
emailStringnullThe email address of the new user

Forgot User Password

HTTP POST

EndpointDescription
https://yts.gs/api/v2/user_forgot_password.json
https://yts.gs/api/v2/user_forgot_password.jsonp
https://yts.gs/api/v2/user_forgot_password.xml
Endpoint is used to get a password reset code sent to their email to in case the user forgot their password

Endpoint Parameters

ParameterRequiredTypeDefaultDescription
emailStringnullThe email address of the user to send the reset password code
application_keyStringnullTo make any POST requests to our API you must use your developer's 'application_key', if you do not have one please apply HERE

Reset User Password

HTTP POST

EndpointDescription
https://yts.gs/api/v2/user_reset_password.json
https://yts.gs/api/v2/user_reset_password.jsonp
https://yts.gs/api/v2/user_reset_password.xml
Endpoint is used to reset the user's password using the password reset code

Endpoint Parameters

ParameterRequiredTypeDefaultDescription
reset_codeStringnullThe reset code which was sent to the user's email
new_passwordStringnullThe newly desired password
application_keyStringnullTo make any POST requests to our API you must use your developer's 'application_key', if you do not have one please apply HERE

Like Movie

HTTP POST

EndpointDescription
https://yts.gs/api/v2/like_movie.json
https://yts.gs/api/v2/like_movie.jsonp
https://yts.gs/api/v2/like_movie.xml
Endpoint is used to send a like (heart) for a specific movie

Endpoint Parameters

ParameterRequiredTypeDefaultDescription
user_keyStringnullThe key that you get from authenticating using the API (Get User Key endpoint)
movie_idInteger (Unsigned)nullThe ID of the movie
application_keyStringnullTo make any POST requests to our API you must use your developer's 'application_key', if you do not have one please apply HERE

Get Movie Bookmarks

HTTP GET

EndpointDescription
https://yts.gs/api/v2/get_movie_bookmarks.json
https://yts.gs/api/v2/get_movie_bookmarks.jsonp
https://yts.gs/api/v2/get_movie_bookmarks.xml
Endpoint is used to get all the current movies which have been bookmarked for a given user

Endpoint Parameters

ParameterRequiredTypeDefaultDescription
user_keyStringnullThe key that you get from authenticating using the API (Get User Key endpoint)
with_rt_ratingsBooleanfalseReturns the list with the Rotten Tomatoes rating included

Examples

URLDescription
https://yts.gs/api/v2/get_movie_bookmarks.json?user_key=1e2b2baddff6234Returns the list of bookmarked movies for an authenticated user

Add Movie Bookmark

HTTP POST

EndpointDescription
https://yts.gs/api/v2/add_movie_bookmark.json
https://yts.gs/api/v2/add_movie_bookmark.jsonp
https://yts.gs/api/v2/add_movie_bookmark.xml
Endpoint is used to add any specific movie to the user's bookmarks

Endpoint Parameters

ParameterRequiredTypeDefaultDescription
user_keyStringnullThe key that you get from authenticating using the API (Get User Key endpoint)
movie_idInteger (Unsigned)nullThe ID of the movie
application_keyStringnullTo make any POST requests to our API you must use your developer's 'application_key', if you do not have one please apply HERE

Delete Movie Bookmark

HTTP POST

EndpointDescription
https://yts.gs/api/v2/delete_movie_bookmark.json
https://yts.gs/api/v2/delete_movie_bookmark.jsonp
https://yts.gs/api/v2/delete_movie_bookmark.xml
Endpoint is used remove movies from the user's bookmarks

Endpoint Parameters

ParameterRequiredTypeDefaultDescription
user_keyStringnullThe key that you get from authenticating using the API (Get User Key endpoint)
movie_idInteger (Unsigned)nullThe ID of the movie
application_keyStringnullTo make any POST requests to our API you must use your developer's 'application_key', if you do not have one please apply HERE

Make Comment

HTTP POST

EndpointDescription
https://yts.gs/api/v2/make_comment.json
https://yts.gs/api/v2/make_comment.jsonp
https://yts.gs/api/v2/make_comment.xml
Endpoint is used allow a user to post a comment on a specific movie

Endpoint Parameters

ParameterRequiredTypeDefaultDescription
user_keyStringnullThe key that you get from authenticating using the API (Get User Key endpoint)
movie_idInteger (Unsigned)nullThe ID of the movie
comment_textInteger (Unsigned)nullThe text that the user wants to submit as the comment
application_keyStringnullTo make any POST requests to our API you must use your developer's 'application_key', if you do not have one please apply HERE

Like Comment

HTTP POST

EndpointDescription
https://yts.gs/api/v2/like_comment.json
https://yts.gs/api/v2/like_comment.jsonp
https://yts.gs/api/v2/like_comment.xml
Endpoint is used allow a user like (heart) a comment

Endpoint Parameters

ParameterRequiredTypeDefaultDescription
user_keyStringnullThe key that you get from authenticating using the API (Get User Key endpoint)
comment_idInteger (Unsigned)nullThe ID of the comment
application_keyStringnullTo make any POST requests to our API you must use your developer's 'application_key', if you do not have one please apply HERE

Report Comment

HTTP POST

EndpointDescription
https://yts.gs/api/v2/report_comment.json
https://yts.gs/api/v2/report_comment.jsonp
https://yts.gs/api/v2/report_comment.xml
Endpoint is used allow a user to report a comment

Endpoint Parameters

ParameterRequiredTypeDefaultDescription
user_keyStringnullThe key that you get from authenticating using the API (Get User Key endpoint)
comment_idInteger (Unsigned)nullThe ID of the comment
application_keyStringnullTo make any POST requests to our API you must use your developer's 'application_key', if you do not have one please apply HERE

Delete Comment

HTTP POST

EndpointDescription
https://yts.gs/api/v2/delete_comment.json
https://yts.gs/api/v2/delete_comment.jsonp
https://yts.gs/api/v2/delete_comment.xml
Endpoint is used allow a user to delete a comment (assuming its their own)

Endpoint Parameters

ParameterRequiredTypeDefaultDescription
user_keyStringnullThe key that you get from authenticating using the API (Get User Key endpoint)
comment_idInteger (Unsigned)nullThe ID of the comment
application_keyStringnullTo make any POST requests to our API you must use your developer's 'application_key', if you do not have one please apply HERE

Make Request

HTTP POST

EndpointDescription
https://yts.gs/api/v2/make_request.json
https://yts.gs/api/v2/make_request.jsonp
https://yts.gs/api/v2/make_request.xml
Endpoint is used allow a user create a movie request

Endpoint Parameters

ParameterRequiredTypeDefaultDescription
user_keyStringnullThe key that you get from authenticating using the API (Get User Key endpoint)
movie_titleStringnullThe title of the movie
request_messageStringnullOptional extra information about the request.
application_keyStringnullTo make any POST requests to our API you must use your developer's 'application_key', if you do not have one please apply HERE