Contraktor"> Contraktor

Warning

Written by an amateur, under heavy development, mostly untested, parts need refactoring and possibly full of bugs. You shouldn't use this yet.

About

Contraktor is a Trakt.tv API wrapper. It covers 100% of the API, performs reasonably extensive checks on the parameters to make sure garbage doesn't get out and implements a few convenience methods.

Contraktor uses Bluebird promises.

Usage

Require Contraktor and instantiate it:

var Contraktor = require('contraktor');

var trakt = new Contraktor({
    endpoint: 'staging',
    headers: {'User-Agent': 'Node.js/MyCoolApp/v1.0.0'}, // default user agent is "Node.js/Contraktor/vX.Y.Z"
    identity: {
        client_id: 'nonsense'
    }
});

endpoint lets you choose which endpoint, 'staging' or 'production', you want to use. Default is 'production'. See methods define_endpoint and switch_endpoint.

headers lets you add or override any of the headers that will be sent automatically to Trakt.tv. The default headers are:

{
    'User-Agent': 'Node.js/Contraktor/v0.6.0',
    'Content-Type': 'application/json',
    'trakt-api-version': 2
}

identity contains your credentials. Before calling any API method, you must set the client_id at the very least. You don't have to do so at construction time; you can use set_identity later.

You can now call any of the following methods.

Non-API methods

define_endpoint

Accepts two arguments, both Strings. The first is the name of the new endpoint, the other the URL. Make sure the URL doesn't have a final slash /.

Add a new endpoint for the API (or overwrite an existing one). staging and production are available out of the box.

trakt.define_endpoint('production', 'http://new-address.tv');
trakt.define_endpoint('homeproxy', 'http://my.home.net');

switch_endpoint

Accepts one argument, the name of the endpoint to switch to. By default Contraktor will hit production and can be switched to staging. Throws a ConfigurationError if you try to switch to a nonexistent endpoint.

trakt.switch_endpoint('staging');

set_headers

Accepts one argument, an object containing the header fields to set. The headers you provide will be merged with the default ones, overwriting anything.

trakt.set_headers({
    'User-Agent': 'Node.js/MyApp/v' + version
});

// You have just changed the user agent. Yayfications!

set_identity

Sets the identity Contraktor should use from now on. The object provided will overwrite whatever identity was being used until now. None of the current fields will be preserved.

At the very minimum you must provide a client_id:

trakt.set_identity({
    client_id: 'NNNOOONNNSEEEEENNNNSSSSEEEE'
});

// you have just lost any tokens, the secret and even the redirect URI.

Here's all the fields you can set:

trakt.set_identity({
    client_id: 'MYEEEEEEEYYYYYYEEEEESSSS',
    client_secret: 'MMMOOOORE NONSSSEEEEENNNSSE'
    access_token: 'OMGICANTREADTHISSTRING',
    refresh_token: 'RANDOMLETTERSANDNUMBERS',
    redirect_uri: 'urn:ietf:wg:oauth:2.0:oob', // or an actual URL, as set in your API app
    expires: 1480232313000  // epoch; set to when the access_token will expire
});

merge_identity

Accepts an object. Same as set_identity, but it won't remove fields that aren't in the object you pass. Fields that have already been set will be overwritten. It's literally just a simple merge. Use this to add new fields to your identity, such as access tokens and the like.

device_auth_step1 and device_auth_step2

These methods implement the device auth flow. Both return a promise.

When you call _step1, Contraktor will use post_oauth_device_code apiary↗ and resolve the promise with the response, so you can instruct the user. Refer to the official docs↗ to learn what the response will contain and how to use that data.

You must call _step2 with the unmodified data returned by _step1. When you do, Contraktor will poll Trakt.tv. If your user authorizes your app, the promise returned by this method will resolve with the full, updated identity (same data that get_identity would return).

If your user denies access to his account or something else goes wrong, the promise will instead reject with a hopefully useful error.

var credentials = {
    client_id: 'long garbage',
    client_secret: 'another one because why the hell not'
};

trakt.set_identity(credentials);

var auth = trakt
    .device_auth_step1()
    .then((res) => {
        console.log('Hello fellow user! On this fine day you are going to open the address ' + res.verification_url + ' and input the following code in the nice text box:');
        console.log(res.user_code);
        console.log('Toodle-loo!')
        return res;
    })
    .then((res) => trakt.device_auth_step2(res))
    .then(console.log)
    .catch(console.log);

The object res in this example looks like this:

{
  "device_code": "d9c126a7706328d808914cfd1e40274b6e009f684b1aca271b9b3f90b3630d64",
  "user_code": "5055CC52",
  "verification_url": "https://trakt.tv/activate",
  "expires_in": 600,
  "interval": 5
}

After a while it will either output the updated identity data on the console or it will reject an error.

refresh_tokens

Doesn't accept any argument. Your tokens will be refreshed, if you have all the required fields set; otherwise it's just a very complicated way of crashing. Whatever identity is currently set will be updated, if needed.

This function will be called automatically the first time you use any API methods after your credentials have expired, provided that your identity has the expires field set.

The returned promise will resolve with your now valid and updated identity.

Before quitting your app, use get_identity to get the tokens so you can store them somewhere. Or don't; nobody gives a damn about your tokens.

API methods

The following list is automatically generated from the API map. Please open an issue if you see anything wrong.

Oauth

oauth_authorize apiary↗

Currently undocumented.

Field	Type	Mandatory	Notes
client_id	String	✓
redirect_uri	String	✓
state	String

post_oauth_device_code apiary↗

Generate new codes to start the device authentication process.

Field	Type	Mandatory	Notes
client_id	String	✓

post_oauth_device_token apiary↗

Poll periodically to check if the user has authorized your app.

Field	Type	Mandatory	Notes
code	String	✓
client_id	String	✓
client_secret	String	✓

post_oauth_revoke apiary↗

🔒 OAuth required

An access_token can be revoked when a user signs out of their Trakt.tv account in your app. This is not required, but might improve the user experience so the user doesn't have an unused app connection hanging around.

Field	Type	Mandatory	Notes
token	String	✓
client_id	String	✓

post_oauth_token apiary↗

🔒 OAuth required

Currently undocumented.

Specify exactly one of the following fields: code, refresh_token

Field	Type	Mandatory	Notes
code	String
refresh_token	String
token	String	✓
client_id	String	✓
client_secret	String	✓
redirect_uri	String	✓
grant_type	String	✓	possible values: authorization_code, refresh_token

Calendars

calendars_all_movies apiary↗

✨ Extensible

Returns all movies with a release date during the time period specified.

Field	Type	Mandatory	Notes
start_date	Date
days	Number	must be greater than 0
client_id	String	✓
extended	String	possible values: min, images, full, full,images, metadata, episodes

calendars_all_shows apiary↗

✨ Extensible

Returns all shows airing during the time period specified.

Field	Type	Mandatory	Notes
start_date	Date
days	Number	must be greater than 0
client_id	String	✓
extended	String	possible values: min, images, full, full,images, metadata, episodes

calendars_all_shows_new apiary↗

✨ Extensible

Returns all new show premieres (season 1, episode 1) airing during the time period specified.

Field	Type	Mandatory	Notes
start_date	Date
days	Number	must be greater than 0
client_id	String	✓
extended	String	possible values: min, images, full, full,images, metadata, episodes

calendars_all_shows_premieres apiary↗

✨ Extensible

Returns all show premieres (any season, episode 1) airing during the time period specified.

Field	Type	Mandatory	Notes
start_date	Date
days	Number	must be greater than 0
client_id	String	✓
extended	String	possible values: min, images, full, full,images, metadata, episodes

calendars_my_movies apiary↗

🔒 OAuth required    ✨ Extensible

Returns all movies with a release date during the time period specified.

Field	Type	Mandatory	Notes
start_date	Date
days	Number	must be greater than 0
client_id	String	✓
token	String	✓
extended	String	possible values: min, images, full, full,images, metadata, episodes

calendars_my_shows apiary↗

🔒 OAuth required    ✨ Extensible

Returns all shows airing during the time period specified.

Field	Type	Mandatory	Notes
start_date	Date
days	Number	must be greater than 0
client_id	String	✓
token	String	✓
extended	String	possible values: min, images, full, full,images, metadata, episodes

calendars_my_shows_new apiary↗

🔒 OAuth required    ✨ Extensible

Returns all new show premieres (season 1, episode 1) airing during the time period specified.

Field	Type	Mandatory	Notes
start_date	Date
days	Number	must be greater than 0
client_id	String	✓
token	String	✓
extended	String	possible values: min, images, full, full,images, metadata, episodes

calendars_my_shows_premieres apiary↗

🔒 OAuth required    ✨ Extensible

Returns all show premieres (any season, episode 1) airing during the time period specified.

Field	Type	Mandatory	Notes
start_date	Date
days	Number	must be greater than 0
client_id	String	✓
token	String	✓
extended	String	possible values: min, images, full, full,images, metadata, episodes

Checkin

delete_checkin apiary↗

🔒 OAuth required

Removes any active checkins, no need to provide a specific item

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓

post_checkin apiary↗

🔒 OAuth required

Check into a movie or episode. This should be tied to a user action to manually indicate they are watching something. The item will display as watching on the site, then automatically switch to watched status once the duration has elapsed.

Specify exactly one of the following fields: movie, episode

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
movie	Complex↗
episode	Complex↗
sharing	Complex↗
message	String
app_version	String
app_date	Date

Comments

comments apiary↗

Returns a single comment and indicates how many replies it has.

Field	Type	Mandatory	Notes
id	Number	✓
client_id	String	✓

comments_replies apiary↗

📄 Paginated

Returns all replies for a comment. It is possible these replies could have replies themselves, so in that case you would just call comments_replies again with the new comment id.

Field	Type	Mandatory	Notes
id	Number	✓
client_id	String	✓
page	Number	must be greater than 1
limit	Number	must be greater than 1; maximum 100

delete_comments apiary↗

🔒 OAuth required

Delete a single comment created within the last hour. This also effectively removes any replies this comment has. The OAuth user must match the author of the comment in order to delete it.

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
id	String, Number	✓

delete_comments_like apiary↗

🔒 OAuth required

Remove a like on a comment.

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
id	Number	✓

post_comments apiary↗

🔒 OAuth required

Add a new comment to a movie, show, season, episode, or list. Make sure to allow and encourage spoilers to be indicated in your app and follow the rules listed above.

Specify exactly one of the following fields: movie, show, season, episode, list

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
movie	Complex↗
show	Complex↗
season	Complex↗
episode	Complex↗
list	Complex↗
comment	String	✓
spoiler	Boolean	✓
sharing	Complex↗
message	String
app_version	String
app_date	Date

post_comments_like apiary↗

🔒 OAuth required

Votes help determine popular comments. Only one like is allowed per comment per user.

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
id	Number	✓

post_comments_replies apiary↗

🔒 OAuth required

Add a new reply to an existing comment. Make sure to allow and encourage spoilers to be indicated in your app.

Field	Type	Mandatory	Notes
id	Number	✓
client_id	String	✓
token	String	✓
comment	String	✓
spoiler	Boolean	✓

put_comments apiary↗

🔒 OAuth required

Update a single comment created within the last hour. The OAuth user must match the author of the comment in order to update it.

Field	Type	Mandatory	Notes
id	Number	✓
client_id	String	✓
token	String	✓
comment	String	✓
spoiler	Boolean	✓

Genres

genres apiary↗

Get a list of all genres, including names and slugs.

Field	Type	Mandatory	Notes
type	String	possible values: movies, shows
client_id	String	✓

Movies

movies apiary↗

✨ Extensible

Returns a single movie's details.

Field	Type	Mandatory	Notes
id	String, Number	✓
client_id	String	✓
extended	String	possible values: min, images, full, full,images, metadata, episodes

movies_aliases apiary↗

Returns all title aliases for a movie. Includes country where name is different.

Field	Type	Mandatory	Notes
id	String, Number	✓
client_id	String	✓

movies_anticipated apiary↗

✨ Extensible    📄 Paginated    🎚 Filterable

Returns the most anticipated movies based on the number of lists a movie appears on.

Field	Type	Mandatory	Notes
client_id	String	✓
extended	String	possible values: min, images, full, full,images, metadata, episodes
page	Number	must be greater than 1
limit	Number	must be greater than 1; maximum 100
query	String
years	Number
genres	String
languages	String
countries	String
runtimes	String
ratings	String
certifications	String

movies_boxoffice apiary↗

✨ Extensible    📄 Paginated

Returns the top 10 grossing movies in the U.S. box office last weekend. Updated every Monday morning.

Field	Type	Mandatory	Notes
client_id	String	✓
extended	String	possible values: min, images, full, full,images, metadata, episodes
page	Number	must be greater than 1
limit	Number	must be greater than 1; maximum 100

movies_collected apiary↗

✨ Extensible    📄 Paginated    🎚 Filterable

Returns the most collected (unique users) movies in the specified time period, defaulting to weekly. All stats are relative to the specific time period.

Field	Type	Mandatory	Notes
period	String	possible values: weekly, monthly, yearly, all
client_id	String	✓
extended	String	possible values: min, images, full, full,images, metadata, episodes
page	Number	must be greater than 1
limit	Number	must be greater than 1; maximum 100
query	String
years	Number
genres	String
languages	String
countries	String
runtimes	String
ratings	String
certifications	String

movies_comments apiary↗

📄 Paginated

Returns all top level comments for a movie. Most recent comments returned first.

Field	Type	Mandatory	Notes
id	String, Number	✓
client_id	String	✓
page	Number	must be greater than 1
limit	Number	must be greater than 1; maximum 100

movies_people apiary↗

Returns all cast and crew for a movie. Each cast member will have a character and a standard person object.

Field	Type	Mandatory	Notes
id	String, Number	✓
client_id	String	✓

movies_played apiary↗

✨ Extensible    📄 Paginated    🎚 Filterable

Returns the most played (a single user can watch multiple times) movies in the specified time period, defaulting to weekly. All stats are relative to the specific time period.

Field	Type	Mandatory	Notes
period	String	possible values: weekly, monthly, yearly, all
client_id	String	✓
extended	String	possible values: min, images, full, full,images, metadata, episodes
page	Number	must be greater than 1
limit	Number	must be greater than 1; maximum 100
query	String
years	Number
genres	String
languages	String
countries	String
runtimes	String
ratings	String
certifications	String

movies_popular apiary↗

✨ Extensible    📄 Paginated    🎚 Filterable

Returns the most popular movies. Popularity is calculated using the rating percentage and the number of ratings.

Field	Type	Mandatory	Notes
client_id	String	✓
extended	String	possible values: min, images, full, full,images, metadata, episodes
page	Number	must be greater than 1
limit	Number	must be greater than 1; maximum 100
query	String
years	Number
genres	String
languages	String
countries	String
runtimes	String
ratings	String
certifications	String

movies_ratings apiary↗

Returns rating (between 0 and 10) and distribution for a movie.

Field	Type	Mandatory	Notes
id	String, Number	✓
client_id	String	✓

movies_related apiary↗

✨ Extensible

Returns related and similar movies.

Field	Type	Mandatory	Notes
id	String, Number	✓
client_id	String	✓
extended	String	possible values: min, images, full, full,images, metadata, episodes

movies_releases apiary↗

✨ Extensible

Returns all releases for a movie including country, certification, release date, release type, and note. The release type can be set to unknown, premiere, limited, theatrical, digital, physical, or tv. The note might have optional info such as the film festival name for a premiere release or Blu-ray specs for a physical release. We pull this info from TMDB.

Field	Type	Mandatory	Notes
id	String, Number	✓
country	String
client_id	String	✓
extended	String	possible values: min, images, full, full,images, metadata, episodes

movies_stats apiary↗

Returns lots of movie stats.

Field	Type	Mandatory	Notes
id	String, Number	✓
client_id	String	✓

movies_translations apiary↗

Returns all translations for a movie, including language and translated values for title, tagline and overview.

Field	Type	Mandatory	Notes
id	String, Number	✓
country	String
client_id	String	✓

movies_trending apiary↗

✨ Extensible    📄 Paginated    🎚 Filterable

Returns all movies being watched right now. Movies with the most users are returned first.

Field	Type	Mandatory	Notes
client_id	String	✓
extended	String	possible values: min, images, full, full,images, metadata, episodes
page	Number	must be greater than 1
limit	Number	must be greater than 1; maximum 100
query	String
years	Number
genres	String
languages	String
countries	String
runtimes	String
ratings	String
certifications	String

movies_updates apiary↗

✨ Extensible    📄 Paginated

Returns all movies updated since the specified UTC date. We recommended storing the date so that you can be efficient using this method moving forward.

Field	Type	Mandatory	Notes
start_date	Date
client_id	String	✓
extended	String	possible values: min, images, full, full,images, metadata, episodes
page	Number	must be greater than 1
limit	Number	must be greater than 1; maximum 100

movies_watched apiary↗

✨ Extensible    📄 Paginated    🎚 Filterable

Returns the most watched (unique users) movies in the specified time period, defaulting to weekly. All stats are relative to the specific time period.

Field	Type	Mandatory	Notes
period	String	possible values: weekly, monthly, yearly, all
client_id	String	✓
extended	String	possible values: min, images, full, full,images, metadata, episodes
page	Number	must be greater than 1
limit	Number	must be greater than 1; maximum 100
query	String
years	Number
genres	String
languages	String
countries	String
runtimes	String
ratings	String
certifications	String

movies_watching apiary↗

Returns all users watching this movie right now.

Field	Type	Mandatory	Notes
id	String, Number	✓
client_id	String	✓

People

people apiary↗

Returns a single person's details.

Field	Type	Mandatory	Notes
id	String, Number	✓
client_id	String	✓

people_movies apiary↗

Returns all movies where this person is in the cast or crew. Each cast object will have a character and a standard movie object.

Field	Type	Mandatory	Notes
id	String, Number	✓
client_id	String	✓

people_shows apiary↗

Returns all movies where this person is in the cast or crew. Each cast object will have a character and a standard show object.

Field	Type	Mandatory	Notes
id	String, Number	✓
client_id	String	✓

Recommendations

delete_recommendations_movies apiary↗

🔒 OAuth required

Hide a movie from getting recommended anymore.

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
id	String, Number	✓

delete_recommendations_shows apiary↗

🔒 OAuth required

Hide a show from getting recommended anymore.

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
id	String, Number	✓

recommendations_movies apiary↗

🔒 OAuth required    ✨ Extensible    📄 Paginated

Personalized movie recommendations for a user.

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
extended	String	possible values: min, images, full, full,images, metadata, episodes
page	Number	must be greater than 1
limit	Number	must be greater than 1; maximum 100

recommendations_shows apiary↗

🔒 OAuth required    ✨ Extensible    📄 Paginated

Personalized show recommendations for a user.

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
extended	String	possible values: min, images, full, full,images, metadata, episodes
page	Number	must be greater than 1
limit	Number	must be greater than 1; maximum 100

Scrobble

post_scrobble_pause apiary↗

🔒 OAuth required

Use this method when the video is paused. The playback progress will be saved and sync_playback can be used to resume the video from this exact position. Unpause a video by calling the post_scrobble_start method again.

Specify exactly one of the following fields: movie, episode

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
movie	Complex↗
episode	Complex↗
progress	Number	✓
app_version	String
app_date	Date

post_scrobble_start apiary↗

🔒 OAuth required

Use this method when the video intially starts playing or is unpaused. This will remove any playback progress if it exists.

Specify exactly one of the following fields: movie, episode

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
movie	Complex↗
episode	Complex↗
progress	Number	✓
app_version	String
app_date	Date

post_scrobble_stop apiary↗

🔒 OAuth required

Use this method when the video is stopped or finishes playing on its own. If the progress is above 80%, the video will be scrobbled and the action will be set to scrobble.

If the progress is less than 80%, it will be treated as a pause and the action will be set to pause. The playback progress will be saved and sync_playback can be used to resume the video from this exact position.

Specify exactly one of the following fields: movie, episode

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
movie	Complex↗
episode	Complex↗
progress	Number	✓
app_version	String
app_date	Date

Search

search apiary↗

✨ Extensible    📄 Paginated    🎚 Filterable

Use this to perform a text query that searches titles, descriptions, translated titles, aliases, and people. Items searched include movies, shows, episodes, people, and lists. Results are ordered by the most relevant score.

Using this same method you can also perform a search by ID, either a Trakt.tv ID or an external one. You can for example learn the IMDB id using the Trakt.tv id.

Field	Type	Mandatory	Notes
type	Array	✓
id_type	String	possible values: trakt, imdb, tmdb, tvdb
id	String, Number
client_id	String	✓
extended	String	possible values: min, images, full, full,images, metadata, episodes
page	Number	must be greater than 1
limit	Number	must be greater than 1; maximum 100
query	String
years	Number
genres	String
languages	String
countries	String
runtimes	String
ratings	String
certifications	String
networks	String
status	String

Shows

shows apiary↗

✨ Extensible

Returns a single shows's details. If you get extended info, the airs object is relative to the show's country. You can use the day, time, and timezone to construct your own date then convert it to whatever timezone your user is in.

Field	Type	Mandatory	Notes
id	String, Number	✓
client_id	String	✓
extended	String	possible values: min, images, full, full,images, metadata, episodes

shows_aliases apiary↗

Returns all title aliases for a show. Includes country where name is different.

Field	Type	Mandatory	Notes
id	String, Number	✓
client_id	String	✓

shows_anticipated apiary↗

✨ Extensible    📄 Paginated    🎚 Filterable

Returns the most anticipated shows based on the number of lists a show appears on.

Field	Type	Mandatory	Notes
client_id	String	✓
extended	String	possible values: min, images, full, full,images, metadata, episodes
page	Number	must be greater than 1
limit	Number	must be greater than 1; maximum 100
query	String
years	Number
genres	String
languages	String
countries	String
runtimes	String
ratings	String
certifications	String
networks	String
status	String

shows_collected apiary↗

✨ Extensible    📄 Paginated    🎚 Filterable

Returns the most collected (unique users) shows in the specified time period, defaulting to weekly. All stats are relative to the specific time period.

Field	Type	Mandatory	Notes
period	String	possible values: weekly, monthly, yearly, all
client_id	String	✓
extended	String	possible values: min, images, full, full,images, metadata, episodes
page	Number	must be greater than 1
limit	Number	must be greater than 1; maximum 100
query	String
years	Number
genres	String
languages	String
countries	String
runtimes	String
ratings	String
certifications	String
networks	String
status	String

shows_comments apiary↗

📄 Paginated

Returns all top level comments for a show. Most recent comments returned first.

Field	Type	Mandatory	Notes
id	String, Number	✓
client_id	String	✓
page	Number	must be greater than 1
limit	Number	must be greater than 1; maximum 100

shows_people apiary↗

Returns all cast and crew for a show. Each cast member will have a character and a standard person object.

The crew object will be broken up into production, art, crew, costume & make-up, directing, writing, sound, and camera (if there are people for those crew positions). Each of those members will have a job and a standard person object.

Field	Type	Mandatory	Notes
id	String, Number	✓
client_id	String	✓

shows_played apiary↗

✨ Extensible    📄 Paginated    🎚 Filterable

Returns the most played (a single user can watch multiple episodes multiple times) shows in the specified time period, defaulting to weekly. All stats are relative to the specific time period.

Field	Type	Mandatory	Notes
period	String	possible values: weekly, monthly, yearly, all
client_id	String	✓
extended	String	possible values: min, images, full, full,images, metadata, episodes
page	Number	must be greater than 1
limit	Number	must be greater than 1; maximum 100
query	String
years	Number
genres	String
languages	String
countries	String
runtimes	String
ratings	String
certifications	String
networks	String
status	String

shows_popular apiary↗

✨ Extensible    📄 Paginated    🎚 Filterable

Returns the most popular shows. Popularity is calculated using the rating percentage and the number of ratings.

Field	Type	Mandatory	Notes
client_id	String	✓
extended	String	possible values: min, images, full, full,images, metadata, episodes
page	Number	must be greater than 1
limit	Number	must be greater than 1; maximum 100
query	String
years	Number
genres	String
languages	String
countries	String
runtimes	String
ratings	String
certifications	String
networks	String
status	String

shows_progress_collection apiary↗

🔒 OAuth required

Returns collection progress for show including details on all seasons and episodes. The next_episode will be the next episode the user should collect, if there are no upcoming episodes it will be set to null. By default, any hidden seasons will be removed from the response and stats. To include these and adjust the completion stats, set the hidden flag to true.

Field	Type	Mandatory	Notes
id	String, Number	✓
hidden	Boolean
specials	Boolean
client_id	String	✓
token	String	✓

shows_ratings apiary↗

Returns rating (between 0 and 10) and distribution for a show

Field	Type	Mandatory	Notes
id	String, Number	✓
client_id	String	✓

shows_related apiary↗

✨ Extensible    📄 Paginated

Returns related and similar shows.

Field	Type	Mandatory	Notes
id	String, Number	✓
client_id	String	✓
extended	String	possible values: min, images, full, full,images, metadata, episodes
page	Number	must be greater than 1
limit	Number	must be greater than 1; maximum 100

shows_seasons apiary↗

✨ Extensible

Returns all seasons for a show including the number of episodes in each season. If you set extended to "episodes", it will return all episodes for all seasons. This is expensive, so evoid doing it unless you really need to. If you specify a season, you will get information on all episodes of that season only.

Field	Type	Mandatory	Notes
id	String, Number	✓
season	Number
client_id	String	✓
extended	String	possible values: min, images, full, full,images, metadata, episodes

shows_seasons_comments apiary↗

📄 Paginated

Returns all top level comments for a season. Most recent comments returned first.

Field	Type	Mandatory	Notes
id	String, Number	✓
season	Number	✓
client_id	String	✓
page	Number	must be greater than 1
limit	Number	must be greater than 1; maximum 100

shows_seasons_episodes apiary↗

✨ Extensible

Returns a single episode's details. All date and times are in UTC and were calculated using the episode's air_date and show's country and air_time.

Field	Type	Mandatory	Notes
id	String, Number	✓
season	Number	✓
episode	Number	✓
client_id	String	✓
extended	String	possible values: min, images, full, full,images, metadata, episodes

shows_seasons_episodes_comments apiary↗

📄 Paginated

Returns all top level comments for an episode. Most recent comments returned first.

Field	Type	Mandatory	Notes
id	String, Number	✓
season	Number	✓
episode	Number	✓
client_id	String	✓
page	Number	must be greater than 1
limit	Number	must be greater than 1; maximum 100

shows_seasons_episodes_ratings apiary↗

Returns rating (between 0 and 10) and distribution for an episode.

Field	Type	Mandatory	Notes
id	String, Number	✓
season	Number	✓
episode	Number	✓
client_id	String	✓

shows_seasons_episodes_stats apiary↗

Returns lots of episode stats.

Field	Type	Mandatory	Notes
id	String, Number	✓
season	Number	✓
episode	Number	✓
client_id	String	✓

shows_seasons_episodes_watching apiary↗

Returns all users watching this episode right now.

Field	Type	Mandatory	Notes
id	String, Number	✓
season	Number	✓
episode	Number	✓
client_id	String	✓

shows_seasons_ratings apiary↗

Returns rating (between 0 and 10) and distribution for a season.

Field	Type	Mandatory	Notes
id	String, Number	✓
season	Number	✓
client_id	String	✓

shows_seasons_stats apiary↗

Returns lots of season stats.

Field	Type	Mandatory	Notes
id	String, Number	✓
season	Number	✓
client_id	String	✓

shows_seasons_watching apiary↗

Returns all users watching this season right now.

Field	Type	Mandatory	Notes
id	String, Number	✓
season	Number	✓
client_id	String	✓

shows_stats apiary↗

Returns lots of show stats.

Field	Type	Mandatory	Notes
id	String, Number	✓
client_id	String	✓

shows_translations apiary↗

Returns all translations for a show, including language and translated values for title and overview.

Field	Type	Mandatory	Notes
id	String, Number	✓
country	String
client_id	String	✓

shows_trending apiary↗

📄 Paginated    🎚 Filterable

Returns all shows being watched right now. Shows with the most users are returned first.

Field	Type	Mandatory	Notes
client_id	String	✓
page	Number	must be greater than 1
limit	Number	must be greater than 1; maximum 100
query	String
years	Number
genres	String
languages	String
countries	String
runtimes	String
ratings	String
certifications	String
networks	String
status	String

shows_updates apiary↗

✨ Extensible    📄 Paginated

Returns all shows updated since the specified UTC date. We recommended storing the date you can be efficient using this method moving forward.

Field	Type	Mandatory	Notes
start_date	Date
client_id	String	✓
extended	String	possible values: min, images, full, full,images, metadata, episodes
page	Number	must be greater than 1
limit	Number	must be greater than 1; maximum 100

shows_watched apiary↗

✨ Extensible    📄 Paginated    🎚 Filterable

Returns the most watched (unique users) shows in the specified time period, defaulting to weekly. All stats are relative to the specific time period.

Field	Type	Mandatory	Notes
period	String	possible values: weekly, monthly, yearly, all
client_id	String	✓
extended	String	possible values: min, images, full, full,images, metadata, episodes
page	Number	must be greater than 1
limit	Number	must be greater than 1; maximum 100
query	String
years	Number
genres	String
languages	String
countries	String
runtimes	String
ratings	String
certifications	String
networks	String
status	String

shows_watching apiary↗

Returns all users watching this show right now.

Field	Type	Mandatory	Notes
id	String, Number	✓
client_id	String	✓

Sync

delete_sync_playback apiary↗

🔒 OAuth required

Remove a playback item from a user's playback progress list.

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
id	Number	✓

post_sync_collection apiary↗

🔒 OAuth required

Add items to a user's collection. Accepts shows, seasons, episodes and movies. If only a show is passed, all episodes for the show will be collected. If seasons are specified, all episodes in those seasons will be collected.

Send a collected_at UTC datetime to mark items as collected in the past. You can also send additional metadata about the media itself to have a very accurate collection. Showcase what is available to watch from your epic HD DVD collection down to your downloaded iTunes movies.

Specify exactly one of the following fields: movies, shows, episodes

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
movies	Complex↗
shows	Complex↗
episodes	Complex↗

post_sync_collection_remove apiary↗

🔒 OAuth required

Remove one or more items from a user's collection.

Specify exactly one of the following fields: movies, shows, episodes

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
movies	Complex↗
shows	Complex↗
episodes	Complex↗

post_sync_history apiary↗

🔒 OAuth required

Add items to a user's watch history. Accepts shows, seasons, episodes and movies. If only a show is passed, all episodes for the show will be added. If seasons are specified, only episodes in those seasons will be added.

Send a watched_at UTC datetime to mark items as watched in the past. This is useful for syncing past watches from a media center.

Specify exactly one of the following fields: movies, shows, episodes

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
movies	Complex↗
shows	Complex↗
episodes	Complex↗

post_sync_history_remove apiary↗

🔒 OAuth required

Remove items from a user's watch history including all watches, scrobbles, and checkins. Accepts shows, seasons, episodes and movies. If only a show is passed, all episodes for the show will be removed. If seasons are specified, only episodes in those seasons will be removed.

You can also send a list of raw history ids to delete single plays from the watched history. The sync_history method will return an individual id for each history item.

Specify exactly one of the following fields: movies, shows, episodes

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
movies	Complex↗
shows	Complex↗
episodes	Complex↗

post_sync_ratings apiary↗

Rate one or more items. Accepts shows, seasons, episodes and movies. If only a show is passed, only the show itself will be rated. If seasons are specified, all of those seasons will be rated.

Send a rated_at UTC datetime to mark items as rated in the past. This is useful for syncing ratings from a media center.

Specify exactly one of the following fields: movies, shows, episodes

Field	Type	Mandatory	Notes
movies	Complex↗
shows	Complex↗
episodes	Complex↗
client_id	String	✓

post_sync_ratings_remove apiary↗

🔒 OAuth required

Remove ratings for one or more items.

Specify exactly one of the following fields: movies, shows, episodes

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
movies	Complex↗
shows	Complex↗
episodes	Complex↗

post_sync_watchlist apiary↗

🔒 OAuth required

Add one of more items to a user's watchlist. Accepts shows, seasons, episodes and movies. If only a show is passed, only the show itself will be added. If seasons are specified, all of those seasons will be added.

Specify exactly one of the following fields: movies, shows, episodes

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
movies	Complex↗
shows	Complex↗
episodes	Complex↗

post_sync_watchlist_remove apiary↗

🔒 OAuth required

Remove one or more items from a user's watchlist.

Specify exactly one of the following fields: movies, shows, episodes

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
movies	Complex↗
shows	Complex↗
episodes	Complex↗

sync_collection apiary↗

🔒 OAuth required    ✨ Extensible

Get all collected items in a user's collection. A collected item indicates availability to watch digitally or on physical media.

If you set extended to "metadata", it will return the additional media_type, resolution, audio, audio_channels and '3d' metadata. It will use null if the metadata isn't set for an item.

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
type	String	✓	possible values: movies, shows
extended	String	possible values: min, images, full, full,images, metadata, episodes

sync_history apiary↗

🔒 OAuth required    ✨ Extensible

Returns movies and episodes that a user has watched, sorted by most recent. You can optionally limit the type to movies or episodes. The id in each history item uniquely identifies the event and can be used to remove individual events by using the post_sync_history_remove method. The action will be set to scrobble, checkin, or watch.

Specify a type and trakt id to limit the history for just that item. If the id is valid, but there is no history, an empty array will be returned.

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
id	Number	requires field type
type	String	✓	possible values: movies, shows
extended	String	possible values: min, images, full, full,images, metadata, episodes

sync_last_activities apiary↗

🔒 OAuth required

This method is a useful first step in the syncing process. We recommended caching these dates locally, then you can compare to know exactly what data has changed recently. This can greatly optimize your syncs so you don't pull down a ton of data only to see nothing has actually changed.

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓

sync_playback apiary↗

🔒 OAuth required

Whenever a scrobble is paused, the playback progress is saved. Use this progress to sync up playback across different media centers or apps. For example, you can start watching a movie in a media center, stop it, then resume on your tablet from the same spot. Each item will have the progress percentage between 0 and 100.

You can optionally specify a type to only get movies or episodes.

By default, all results will be returned. However, you can send a limit if you only need a few recent results for something like an "on deck" feature.

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
type	String	possible values: movies, episodes

sync_ratings apiary↗

🔒 OAuth required    ✨ Extensible

Get a user's ratings filtered by type. You can optionally filter for a specific rating between 1 and 10.

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
type	String	possible values: movies, shows, seasons, episodes, all
rating	Number	possible values: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
extended	String	possible values: min, images, full, full,images, metadata, episodes

sync_watched apiary↗

🔒 OAuth required    ✨ Extensible

Returns all movies or shows a user has watched.

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
type	String	✓	possible values: movies, shows
extended	String	possible values: min, images, full, full,images, metadata, episodes

sync_watchlist apiary↗

🔒 OAuth required    ✨ Extensible

Returns all items in a user's watchlist filtered by type. When an item is watched, it will be automatically removed from the watchlist.

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
type	String	possible values: movies, shows, seasons, episodes
extended	String	possible values: min, images, full, full,images, metadata, episodes

Users

delete_users_follow apiary↗

🔓 OAuth optional

Unfollow someone you already follow.

Field	Type	Mandatory	Notes
client_id	String	✓
token	String
username	String	✓

delete_users_lists apiary↗

🔒 OAuth required

Remove a custom list and all items it contains.

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
id	String, Number	✓
username	String	✓

delete_users_lists_like apiary↗

🔒 OAuth required

Remove a like on a list.

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
id	String, Number	✓
username	String	✓

delete_users_requests apiary↗

🔒 OAuth required

Deny a follower using the id of the request.

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
id	String, Number	✓

post_users_follow apiary↗

🔓 OAuth optional

Follow a user. If the user has a private profile, the follow request will require approval (approved_at will be null). If a user is public, they will be followed immediately (approved_at will have a date).

Field	Type	Mandatory	Notes
client_id	String	✓
token	String
username	String	✓

post_users_lists apiary↗

🔓 OAuth optional

Create a new custom list. The name is the only required field, but the other info is recommended to ask for.

Field	Type	Mandatory	Notes
client_id	String	✓
token	String
username	String	✓
name	String	✓
description	String
privacy	String	possible values: private, friends, public
display_numbers	Boolean
allow_comments	Boolean
id	String, Number

post_users_lists_items apiary↗

🔒 OAuth required

Add one or more items to a custom list. Items can be movies, shows, seasons, episodes, or people.

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
id	String, Number	✓
username	String	✓

post_users_lists_items_remove apiary↗

🔒 OAuth required

Remove one or more items from a custom list.

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
id	String, Number	✓
username	String	✓

post_users_lists_like apiary↗

🔒 OAuth required

Votes help determine popular lists. Only one like is allowed per list per user.

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
id	String, Number	✓
username	String	✓

post_users_requests apiary↗

🔒 OAuth required

Approve a follower using the id of the request.

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
id	String, Number	✓

users apiary↗

🔓 OAuth optional

Get a user's profile information. If the user is private, info will only be returned if you send OAuth and are either that user or an approved follower.

Field	Type	Mandatory	Notes
client_id	String	✓
token	String
username	String	✓

users_collection apiary↗

🔓 OAuth optional    ✨ Extensible

Get all collected items in a user's collection. A collected item indicates availability to watch digitally or on physical media.

If you set extended to "metadata", it will return the additional media_type, resolution, audio, audio_channels and '3d' metadata. It will use null if the metadata isn't set for an item.

Field	Type	Mandatory	Notes
client_id	String	✓
token	String
username	String	✓
type	String	possible values: movies, shows
extended	String	possible values: min, images, full, full,images, metadata, episodes

users_comments apiary↗

🔓 OAuth optional    📄 Paginated

Returns comments a user has posted sorted by most recent.

Field	Type	Mandatory	Notes
client_id	String	✓
token	String
username	String	✓
comment_type	String	possible values: all, reviews, shouts
type	String	possible values: all, movies, shows, seasons, episodes, lists; requires field comment_type
page	Number	must be greater than 1
limit	Number	must be greater than 1; maximum 100

users_followers apiary↗

🔓 OAuth optional

Returns all followers including when the relationship began.

Field	Type	Mandatory	Notes
client_id	String	✓
token	String
username	String	✓

users_friends apiary↗

🔓 OAuth optional

Returns all friends for a user including when the relationship began. Friendship is a 2 way relationship where each user follows the other

Field	Type	Mandatory	Notes
client_id	String	✓
token	String
username	String	✓

users_hidden apiary↗

🔒 OAuth required    📄 Paginated

Get hidden items for a section. This will return an array of standard media objects. You can optionally limit the type of results to return.

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
section	String	possible values: calendar, progress_watched, progress_collected, recommendations
type	String	possible values: movie, show, season
page	Number	must be greater than 1
limit	Number	must be greater than 1; maximum 100

users_history apiary↗

🔓 OAuth optional    📄 Paginated

Returns movies and episodes that a user has watched, sorted by most recent. You can optionally limit the type to movies or episodes.

Field	Type	Mandatory	Notes
client_id	String	✓
token	String
username	String	✓
type	String	possible values: movies, shows, seasons, episodes
id	Number
page	Number	must be greater than 1
limit	Number	must be greater than 1; maximum 100

users_likes apiary↗

🔒 OAuth required    📄 Paginated

Get items a user likes. This will return an array of standard media objects. You can optionally limit the type of results to return.

Field	Type	Mandatory	Notes
client_id	String	✓
token	String	✓
type	String	possible values: comments, lists
page	Number	must be greater than 1
limit	Number	must be greater than 1; maximum 100

users_lists apiary↗

🔓 OAuth optional

Returns all custom lists for a user. Use users_lists_items to get the actual items a specific list contains. Specify an id to get a single custom list.

Field	Type	Mandatory	Notes
client_id	String	✓
token	String
username	String	✓
id	String, Number

`users_lists_c