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 = ; var trakt = 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;trakt;
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;
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; // 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; // you have just lost any tokens, the secret and even the redirect URI.
Here's all the fields you can set:
trakt;
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; var auth = trakt ;
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_comments
apiary↗
📄 Paginated
Returns all top level comments for a list. Most recent comments returned first.
Field | Type | Mandatory | Notes |
---|---|---|---|
id | String, Number | ✓ | |
username | String | ✓ | |
client_id | String | ✓ | |
page | Number | must be greater than 1 | |
limit | Number | must be greater than 1; maximum 100 |
users_lists_items
apiary↗
🔒 OAuth required
Get all items on a custom list. Items can be movies, shows, seasons, episodes, or people. The list of items will be sorted by ascending rank
.
Field | Type | Mandatory | Notes |
---|---|---|---|
client_id | String | ✓ | |
token | String | ✓ | |
id | String, Number | ✓ | |
username | String | ✓ |
users_ratings
apiary↗
🔓 OAuth optional
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 | ||
username | String | ✓ | |
type | String | possible values: movies , shows , seasons , episodes |
|
rating | Number | possible values: 1 , 2 , 3 , 4 , 5 , 6 , 7 , 8 , 9 , 10 |
users_requests
apiary↗
🔒 OAuth required
List a user's pending follow requests so they can either approve or deny them.
Field | Type | Mandatory | Notes |
---|---|---|---|
client_id | String | ✓ | |
token | String | ✓ |
users_settings
apiary↗
🔒 OAuth required
Get the user's settings so you can align your app's experience with what they're used to on the trakt website.
Field | Type | Mandatory | Notes |
---|---|---|---|
client_id | String | ✓ | |
token | String | ✓ |
users_stats
apiary↗
🔓 OAuth optional
Returns stats about the movies, shows, and episodes a user has watched, collected, and rated.
Field | Type | Mandatory | Notes |
---|---|---|---|
client_id | String | ✓ | |
token | String | ||
username | String | ✓ |
users_watched
apiary↗
🔓 OAuth optional
Returns all movies or shows a user has watched sorted by most plays.
Field | Type | Mandatory | Notes |
---|---|---|---|
client_id | String | ✓ | |
token | String | ||
username | String | ✓ | |
type | String | ✓ | possible values: movies , shows |
users_watching
apiary↗
🔓 OAuth optional
Returns a movie or episode if the user is currently watching something. If they are not, it returns no data.
Field | Type | Mandatory | Notes |
---|---|---|---|
client_id | String | ✓ | |
token | String | ||
username | String | ✓ |
users_watchlist
apiary↗
🔓 OAuth optional
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 | ||
username | String | ✓ | |
type | String | possible values: movies , shows , seasons , episodes |