Overview

The Letterboxd API provides access to data from the Letterboxd.com service.

The API consists of endpoints that must be called using HTTPS. Each endpoint URL takes the form of https://api.letterboxd.com/api/v0/ENDPOINT_PATH and should be called using the method specified in the relevant documentation (GET, POST, PATCH or DELETE).

For GET requests, parameters other than the path parameter (if one is specified for the endpoint) should be included as query parameters in the URL. For POST, PATCH and DELETE requests, all required parameters should be included in JSON format within the body of the request. For PATCH requests, you need only include the parameters that are to be changed as a result of the request. If PATCH requests aren’t supported by your client, you can specify a header of X-HTTP-Method-Override: PATCH to simulate these.

Entities are identified in the API by Letterboxd ID (or LID), an alpha-numeric string value that is returned by the API where appropriate. The LID of a member, film, review or list is included in the response headers of an HTTPS request for the corresponding page on our website (as x-letterboxd-identifier). In addition, film, review and list LIDs can be found on our website as the path portion of the content’s shareable boxd.it URL, and member LIDs can be found via the shareable boxd.it URL of the member’s profile in our iOS app. Making a HEAD request to our website is the fastest way to obtain the LID for a given member, film, review or list if you know its URL.

In all cases the response from an endpoint will be a JSON object, with HTTP status codes indicating successful results and error states. Where cursor pagination is provided, there is an enforced limit of 100,000 objects returned in the paginated data, to discourage API consumers from copying our complete dataset.

Authentication

The Letterboxd API uses standard OAuth 2 Resource Owner and Refresh Token authorization flows to grant access to an authenticated member via an access token, which may be refreshed at regular intervals to keep the member signed in. When generating or refreshing an access token, make a form request to the /auth/token endpoint with Content-Type: application/x-www-form-urlencoded and Accept: application/json headers, and request body parameters as follows:

Generate a token

grant_type Required string Use value: password
username Required string The member’s username or email address.
password Required string The member’s password.

Refresh a token

grant_type Required string Use value: refresh_token
refresh_token Required string Your current refresh token value for the member.

The “Bearer” access token generated for a member via this process must be included with all POST, PATCH and DELETE actions (and with some GET actions, as detailed in the documentation below), using an Authorization: Bearer [TOKEN] request header.

You must refresh a member’s access token before it expires, according to the expires_in parameter of the current refresh token. If the access token expires, you’ll need to use the member’s credentials to generate a new token.

Request signing

All API requests must be signed in the following way:

Create a salted string of the form [METHOD]\u0000[URL]\u0000[BODY], where [METHOD] is GET, POST, etc., [URL] is the fully-qualified request URL including the apikey, nonce, timestamp and any other method parameters, and [BODY] is a JSON-encoded string (for POST, PATCH and DELETE requests) or empty (for GET requests). Next, create a [SIGNATURE] from the salted string by applying a lower-case HMAC/SHA-256 transformation, using your API Secret, and append it to your API request [URL] as the final query parameter: …&signature=[SIGNATURE] (the resulting request [URL] should contain at least apikey, nonce, timestamp and signature parameters).

Notes: you must specify a Content-Type: application/json request header if [BODY] is JSON-encoded. \u0000 is the unicode representation of the null byte (please ensure this character is represented according to the conventions of your platform or framework, rather than including the literal string "\u0000"). The apikey parameter is your supplied API Key. The nonce parameter should be a UUID string and must be unique for each API request. The timestamp parameter is the number of seconds since Jan 1, 1970 (UTC).

Endpoints

POST /apple-iap/subscription

Process an Apple In-app Purchase receipt.

Response

200

Success

AppleIAPSubscriptionResponse
401

There is no authenticated member

POST /auth/forgotten-password-request

Request a link via email to reset the password for a member’s account.

Response

204

Success (the email was dispatched if it matched an existing account)

400

Bad request

429

Too many forgotten password requests have been received for this email address. The email is probably in the member’s spam folder

GET /auth/get-login-token

Generate a single-use token for the current member, which can be used to sign the member into the Letterboxd website by passing it as the value of the urt query parameter.

Calls to this endpoint must include the access token for an authenticated member (see Authentication).

Response

200

Success

LoginTokenResponse
400

Bad request

401

There is no authenticated member, or the authenticated member does not own the resource

POST /auth/revoke

Response

default

successful operation

POST /auth/token

Use a member’s credentials to sign in and receive an authentication token.

Use this endpoint to generate or refresh an auth token. See Authentication for more details.

Response

200

Success

AccessToken
400

The credentials were not correct for the member, or the account was not found

OAuthError

GET /auth/username-check

Check if a username is available to register.

Use this endpoint to check the validity and availability of a given username. Usernames must be between 2 and 15 characters long and may only contain upper or lowercase letters, numbers or the underscore (_) character. Usernames associated with deactivated accounts are not automatically released to the pool of available names (members will need to contact Letterboxd Support for assistance).

Parameters

username Required query string

The username to check.

Response

200

Success

UsernameCheckResponse

DELETE /comment/{id}

Delete a comment.

Calls to this endpoint must include the access token for an authenticated member (see Authentication). Comments may be deleted by their owner, or by the owner of the thread to which they are posted.

Parameters

id Required path string

The LID of the comment/​reply.

Response

204

Success

400

Bad request

401

There is no authenticated member, or the authenticated member does not own the resource

403

The window for deleting this comment has expired

404

No comment matches the specified ID

PATCH /comment/{id}

Update the message portion of a comment.

Calls to this endpoint must include the access token for an authenticated member (see Authentication). Comments may only be edited by their owner.

Parameters

id Required path string

The LID of the comment/​reply.

Response

200

Completed, possibly with messages

CommentUpdateResponse
401

There is no authenticated member, or the authenticated member does not own the resource

404

No comment matches the specified ID

POST /comment/{id}/report

Report a comment by ID.

Calls to this endpoint must include the access token for an authenticated member (see Authentication).

Parameters

id Required path string

The LID of the comment/​reply.

Response

204

Success

401

There is no authenticated member

404

No comment matches the specified ID

GET /contributor/{id}

Get details about a film contributor by ID.

Contributors include the film’s director(s), cast, crew and studio(s).

Parameters

id Required path string

The LID of the contributor.

Response

200

Success

Contributor
404

No contributor matches the specified ID

GET /contributor/{id}/contributions

A cursored window over the list of contributions to films for a contributor.

Use the ‘next’ cursor to move through the list

Parameters

id Required path string

The LID of the contributor.

cursor query string

The pagination cursor.

perPage query integer

The number of items to include per page (default is 20, maximum is 100).

filmId query
string[]

multiple parameters (filmId=aaa&filmId=bbb)

Specify up to 100 Letterboxd IDs or TMDB IDs prefixed with tmdb:, or IMDB IDs prefixed with imdb:

genre query string

Specify the LID of a genre to limit films to those within the specified genre.

includeGenre query
string[]

multiple parameters (includeGenre=aaa&includeGenre=bbb)

Specify the LID of up to 100 genres to limit films to those within all of the specified genres.

excludeGenre query
string[]

multiple parameters (excludeGenre=aaa&excludeGenre=bbb)

Specify the LID of up to 100 genres to limit films to those within none of the specified genres.

country query string

Specify the ISO 3166-1 defined code of the country to limit films to those produced in the specified country.

language query string

Specify the ISO 639-1 defined code of the language to limit films to those using the specified spoken language.

decade query integer

Specify the starting year of a decade (must end in 0) to limit films to those released during the decade.

year query integer

Specify a year to limit films to those released during that year.

service query string

Specify the ID of a supported service to limit films to those available from that service. The list of available services can be found by using the /films/film-services endpoint.

where query
enum[] ∈ {Released, NotReleased, InWatchlist, NotInWatchlist, Logged, NotLogged, Reviewed, NotReviewed, Owned, NotOwned, Rated, NotRated, Liked, NotLiked, WatchedFromWatchlist, Watched, NotWatched, FeatureLength, NotFeatureLength, Fiction, Film, TV}

multiple parameters (where=aaa&where=bbb)

Specify one or more values to limit the list of films accordingly.

member query string

Specify the LID of a member to limit the returned films according to the value set in memberRelationship or to access the MemberRating* sort options.

memberRelationship query enum ∈ {Ignore, Watched (default), NotWatched, Liked, NotLiked, Rated, NotRated, InWatchlist, NotInWatchlist, Favorited}

Must be used in conjunction with member. Defaults to Watched. Specify the type of relationship to limit the returned films accordingly. Use Ignore if you only intend to specify the member for use with sort=MemberRating*.

includeFriends query enum ∈ {None (default), All, Only}

Must be used in conjunction with member. Defaults to None, which only returns films from the member’s account. Use Only to return films from the member’s friends, and All to return films from both the member and their friends.

tag query string

DEPRECATED Use tagCode instead.

tagCode query string

Specify a tag code to limit the returned films to those tagged accordingly.

tagger query string

Must be used with tagCode. Specify the LID of a member to focus the tag filter on the member.

includeTaggerFriends query enum ∈ {None (default), All, Only}

Must be used in conjunction with tagger. Defaults to None, which filters tags set by the member. Use Only to filter tags set by the member’s friends, and All to filter tags set by both the member and their friends.

sort query enum ∈ {FilmName, ReleaseDateLatestFirst, ReleaseDateEarliestFirst, AuthenticatedMemberRatingHighToLow, AuthenticatedMemberRatingLowToHigh, MemberRatingHighToLow, MemberRatingLowToHigh, AverageRatingHighToLow, AverageRatingLowToHigh, RatingHighToLow, RatingLowToHigh, FilmDurationShortestFirst, FilmDurationLongestFirst, FilmPopularity (default), FilmPopularityThisWeek, FilmPopularityThisMonth, FilmPopularityThisYear}

The order in which the films should be returned. Defaults to FilmPopularity, which is an all-time measurement of the amount of activity the film has received. The *WithFriends values are only available to signed-in members and consider popularity amongst the signed-in member’s friends.The AuthenticatedMember* values are only available to signed-in members.The MemberRating values must be used in conjunction with member and are only available when specifying a single member (i.e. IncludeFriends=None).DEPRECATED The Rating* options are deprecated in favor of AverageRating*.

type query enum ∈ {Director, CoDirector, Actor, Producer, Writer, Editor, Cinematography, ProductionDesign, ArtDirection, SetDecoration, VisualEffects, Composer, Sound, Costumes, MakeUp, Studio}

The type of contribution.

Response

200

Success

FilmContributionsResponse
404

No contributor matches the specified ID

GET /film-collection/{id}

Get details about a film collection by ID. The response will include the film relationships for the signed-in member and the member indicated by the member LID if specified.

Parameters

id Required path string

The LID of the film collection.

filmId query
string[]

multiple parameters (filmId=aaa&filmId=bbb)

Specify up to 100 Letterboxd IDs or TMDB IDs prefixed with tmdb:, or IMDB IDs prefixed with imdb:

genre query string

Specify the LID of a genre to limit films to those within the specified genre.

includeGenre query
string[]

multiple parameters (includeGenre=aaa&includeGenre=bbb)

Specify the LID of up to 100 genres to limit films to those within all of the specified genres.

excludeGenre query
string[]

multiple parameters (excludeGenre=aaa&excludeGenre=bbb)

Specify the LID of up to 100 genres to limit films to those within none of the specified genres.

country query string

Specify the ISO 3166-1 defined code of the country to limit films to those produced in the specified country.

language query string

Specify the ISO 639-1 defined code of the language to limit films to those using the specified spoken language.

decade query integer

Specify the starting year of a decade (must end in 0) to limit films to those released during the decade.

year query integer

Specify a year to limit films to those released during that year.

service query string

Specify the ID of a supported service to limit films to those available from that service. The list of available services can be found by using the /films/film-services endpoint.

where query
enum[] ∈ {Released, NotReleased, InWatchlist, NotInWatchlist, Logged, NotLogged, Reviewed, NotReviewed, Owned, NotOwned, Rated, NotRated, Liked, NotLiked, WatchedFromWatchlist, Watched, NotWatched, FeatureLength, NotFeatureLength, Fiction, Film, TV}

multiple parameters (where=aaa&where=bbb)

Specify one or more values to limit the list of films accordingly.

member query string

Specify the LID of a member to limit the returned films according to the value set in memberRelationship or to access the MemberRating* sort options.

memberRelationship query enum ∈ {Ignore, Watched (default), NotWatched, Liked, NotLiked, Rated, NotRated, InWatchlist, NotInWatchlist, Favorited}

Must be used in conjunction with member. Defaults to Watched. Specify the type of relationship to limit the returned films accordingly. Use Ignore if you only intend to specify the member for use with sort=MemberRating*.

includeFriends query enum ∈ {None (default), All, Only}

Must be used in conjunction with member. Defaults to None, which only returns films from the member’s account. Use Only to return films from the member’s friends, and All to return films from both the member and their friends.

tag query string

DEPRECATED Use tagCode instead.

tagCode query string

Specify a tag code to limit the returned films to those tagged accordingly.

tagger query string

Must be used with tagCode. Specify the LID of a member to focus the tag filter on the member.

includeTaggerFriends query enum ∈ {None (default), All, Only}

Must be used in conjunction with tagger. Defaults to None, which filters tags set by the member. Use Only to filter tags set by the member’s friends, and All to filter tags set by both the member and their friends.

sort query enum ∈ {FilmName, ReleaseDateLatestFirst, ReleaseDateEarliestFirst, AuthenticatedMemberRatingHighToLow, AuthenticatedMemberRatingLowToHigh, MemberRatingHighToLow, MemberRatingLowToHigh, AverageRatingHighToLow, AverageRatingLowToHigh, FilmDurationShortestFirst, FilmDurationLongestFirst, FilmPopularity (default), FilmPopularityThisWeek, FilmPopularityThisMonth, FilmPopularityThisYear, FilmPopularityWithFriends, FilmPopularityWithFriendsThisWeek, FilmPopularityWithFriendsThisMonth, FilmPopularityWithFriendsThisYear}

The order in which the films should be returned. Defaults to FilmPopularity, which is an all-time measurement of the amount of activity the film has received. The *WithFriends values are only available to signed-in members and consider popularity amongst the signed-in member’s friends.The AuthenticatedMember* values are only available to signed-in members.The MemberRating values must be used in conjunction with member and are only available when specifying a single member (i.e. IncludeFriends=None).

Response

200

Success

FilmCollection
404

No film collection matches the specified ID

GET /film/{id}

Get details about a film by ID.

Parameters

id Required path string

The LID of the film.

Response

200

Success

Film
404

No film matches the specified ID

GET /film/{id}/availability

Get availability data for a film by ID. Only available to first-party API clients.

Parameters

id Required path string

The LID of the film.

Response

200

Success

FilmAvailabilityResponse
404

No film matches the specified ID

GET /film/{id}/friends

Get details of the authenticated member’s friends’ relationship with a film by ID.

Parameters

id Required path string

The LID of the film.

Response

200

Success

FilmRelationship
401

There is no authenticated member

404

No film matches the specified ID

GET /film/{id}/me

Get details of the authenticated member’s relationship with a film by ID.

Calls to this endpoint must include the access token for an authenticated member (see Authentication).

Parameters

id Required path string

The LID of the film.

Response

200

Success

FilmRelationship
401

There is no authenticated member

404

No film matches the specified ID

PATCH /film/{id}/me

Update the authenticated member’s relationship with a film by ID.

Calls to this endpoint must include the access token for an authenticated member (see Authentication).

Parameters

id Required path string

The LID of the film.

Response

200

Success

FilmRelationshipUpdateResponse
401

There is no authenticated member

404

No film matches the specified ID

GET /film/{id}/members

Get details of members’ relationships with a film by ID.

Parameters

id Required path string

The LID of the film.

cursor query string

The pagination cursor.

perPage query integer

The number of items to include per page (default is 20, maximum is 100).

sort query enum ∈ {Date (default), Name, MemberPopularity, MemberPopularityThisWeek, MemberPopularityThisMonth, MemberPopularityThisYear, MemberPopularityWithFriends, MemberPopularityWithFriendsThisWeek, MemberPopularityWithFriendsThisMonth, MemberPopularityWithFriendsThisYear}

Defaults to Date, which has different semantics based on the request:When review is specified, members who most recently liked the review appear first.When list is specified, members who most recently liked the list appear first.When film is specified and filmRelationship=Watched, members who most recently watched the film appear first.When film is specified and filmRelationship=Liked, members who most recently liked the film appear first.When film is specified and filmRelationship=InWatchlist, members who most recently added the film to their watchlist appear first.When member is specified and memberRelationship=IsFollowing, most recently followed members appear first.When member is specified and memberRelationship=IsFollowedBy, most recent followers appear first.Otherwise, members who most recently joined the site appear first.The *WithFriends values are only available to authenticated members and consider popularity amongst the member’s friends.

member query string

Specify the LID of a member to return members who follow or are followed by that member.

memberRelationship query enum ∈ {IsFollowing (default), IsFollowedBy}

Must be used in conjunction with member. Defaults to IsFollowing, which returns the list of members followed by the member. Use IsFollowedBy to return the list of members that follow the member.

filmRelationship query enum ∈ {Ignore, Watched (default), NotWatched, Liked, NotLiked, Rated, NotRated, InWatchlist, NotInWatchlist, Favorited}

Must be used in conjunction with film. Defaults to Watched, which returns the list of members who have seen the film. Specify the type of relationship to limit the returned members accordingly.

Response

200

Success

MemberFilmRelationshipsResponse
404

No film matches the specified ID

POST /film/{id}/report

Report a film by ID.

Calls to this endpoint must include the access token for an authenticated member (see Authentication).

Parameters

id Required path string

The LID of the film.

Response

204

Success

401

There is no authenticated member

404

No film matches the specified ID

GET /film/{id}/statistics

Get statistical data about a film by ID.

Parameters

id Required path string

The LID of the film.

Response

200

Success

FilmStatistics
404

No film matches the specified ID

GET /films

A cursored window over the list of films.

Use the ‘next’ cursor to move through the list. The response will include the film relationships for the signed-in member and the member indicated by the member LID if specified.

Parameters

cursor query string

The pagination cursor.

perPage query integer

The number of items to include per page (default is 20, maximum is 100).

filmId query
string[]

multiple parameters (filmId=aaa&filmId=bbb)

Specify up to 100 Letterboxd IDs or TMDB IDs prefixed with tmdb:, or IMDB IDs prefixed with imdb:

genre query string

Specify the LID of a genre to limit films to those within the specified genre.

includeGenre query
string[]

multiple parameters (includeGenre=aaa&includeGenre=bbb)

Specify the LID of up to 100 genres to limit films to those within all of the specified genres.

excludeGenre query
string[]

multiple parameters (excludeGenre=aaa&excludeGenre=bbb)

Specify the LID of up to 100 genres to limit films to those within none of the specified genres.

country query string

Specify the ISO 3166-1 defined code of the country to limit films to those produced in the specified country.

language query string

Specify the ISO 639-1 defined code of the language to limit films to those using the specified spoken language.

decade query integer

Specify the starting year of a decade (must end in 0) to limit films to those released during the decade.

year query integer

Specify a year to limit films to those released during that year.

service query string

Specify the ID of a supported service to limit films to those available from that service. The list of available services can be found by using the /films/film-services endpoint.

where query
enum[] ∈ {Released, NotReleased, InWatchlist, NotInWatchlist, Logged, NotLogged, Reviewed, NotReviewed, Owned, NotOwned, Rated, NotRated, Liked, NotLiked, WatchedFromWatchlist, Watched, NotWatched, FeatureLength, NotFeatureLength, Fiction, Film, TV}

multiple parameters (where=aaa&where=bbb)

Specify one or more values to limit the list of films accordingly.

member query string

Specify the LID of a member to limit the returned films according to the value set in memberRelationship or to access the MemberRating* sort options.

memberRelationship query enum ∈ {Ignore, Watched (default), NotWatched, Liked, NotLiked, Rated, NotRated, InWatchlist, NotInWatchlist, Favorited}

Must be used in conjunction with member. Defaults to Watched. Specify the type of relationship to limit the returned films accordingly. Use Ignore if you only intend to specify the member for use with sort=MemberRating*.

includeFriends query enum ∈ {None (default), All, Only}

Must be used in conjunction with member. Defaults to None, which only returns films from the member’s account. Use Only to return films from the member’s friends, and All to return films from both the member and their friends.

tag query string

DEPRECATED Use tagCode instead.

tagCode query string

Specify a tag code to limit the returned films to those tagged accordingly.

tagger query string

Must be used with tagCode. Specify the LID of a member to focus the tag filter on the member.

includeTaggerFriends query enum ∈ {None (default), All, Only}

Must be used in conjunction with tagger. Defaults to None, which filters tags set by the member. Use Only to filter tags set by the member’s friends, and All to filter tags set by both the member and their friends.

sort query enum ∈ {FilmName, DateLatestFirst, DateEarliestFirst, ReleaseDateLatestFirst, ReleaseDateEarliestFirst, AuthenticatedMemberRatingHighToLow, AuthenticatedMemberRatingLowToHigh, MemberRatingHighToLow, MemberRatingLowToHigh, AverageRatingHighToLow, AverageRatingLowToHigh, RatingHighToLow, RatingLowToHigh, FilmDurationShortestFirst, FilmDurationLongestFirst, FilmPopularity (default), FilmPopularityThisWeek, FilmPopularityThisMonth, FilmPopularityThisYear, FilmPopularityWithFriends, FilmPopularityWithFriendsThisWeek, FilmPopularityWithFriendsThisMonth, FilmPopularityWithFriendsThisYear}

The order in which the films should be returned. Defaults to FilmPopularity, which is an all-time measurement of the amount of activity the film has received. The *WithFriends values are only available to signed-in members and consider popularity amongst the signed-in member’s friends.The Date values are only available when member is specified and using a memberRelationship of Watched, Liked, Rated or InWatchlistThe AuthenticatedMember* values are only available to signed-in members.The MemberRating values must be used in conjunction with member and are only available when specifying a single member (i.e. IncludeFriends=None).DEPRECATED The Rating* options are deprecated in favor of AverageRating*.

Response

200

Success

FilmsResponse

GET /films/autocomplete

DEPRECATED Please use /search?input={input}&searchMethod=Autocomplete&include=FilmSearchItem instead. Get a list of films matching a given search term.

Titles are returned in order of relevance. Up to 100 films will be returned.

Parameters

perPage query integer

The number of items to include per page (default is 20, maximum is 100).

input Required query string

The word, partial word or phrase to match against.

adult query boolean

Whether to include adult content in search results. Default to false.

Response

200

Success

FilmsAutocompleteResponse

GET /films/countries

Get a list of countries supported by the /films endpoint.

Countries are returned in alphabetical order.

Response

200

Success

CountriesResponse

GET /films/film-services

Get a list of services supported by the /films endpoint.

Services are returned in logical order. Some services (including ‘My Services’ options) are only available to paying members, so results will vary based on the authenticated member’s status.

Response

200

Success

FilmServicesResponse

GET /films/genres

Get a list of genres supported by the /films endpoint.

Genres are returned in alphabetical order.

Response

200

Success

GenresResponse

GET /films/languages

Get a list of languages supported by the /films endpoint.

Languages are returned in alphabetical order.

Response

200

Success

LanguagesResponse

DELETE /list/{id}

Delete a list by ID.

Calls to this endpoint must include the access token for an authenticated member (see Authentication).

Parameters

id Required path string

The LID of the list.

Response

204

Success

400

Bad request

401

There is no authenticated member

403

The authenticated member does not own the specified list

404

No list matches the specified ID

GET /list/{id}

Get details of a list by ID.

Parameters

id Required path string

The LID of the list.

Response

200

Success

List
404

No list matches the specified ID

PATCH /list/{id}

Update a list by ID.

Calls to this endpoint must include the access token for an authenticated member (see Authentication).

Parameters

id Required path string

The LID of the list.

Response

200

Success

ListUpdateResponse
400

Bad request

401

There is no authenticated member, or the authenticated member does not own the resource

404

No list matches the specified ID

GET /list/{id}/comments

A cursored window over the comments for a list.

Use the ‘next’ cursor to move through the comments.

Parameters

id Required path string

The LID of the list.

cursor query string

The pagination cursor.

perPage query integer

The number of items to include per page (default is 20, maximum is 100).

sort query enum ∈ {Date, DateLatestFirst, Updates}

Defaults to Date. The Updates sort order returns newest content first. Use this to get the most recently posted or edited comments, and pass includeDeletions=true to remain consistent in the case where a comment has been deleted.

includeDeletions query boolean

Use this to discover any comments that were deleted.

Response

200

Success

ListCommentsResponse
404

No list matches the specified ID

POST /list/{id}/comments

Create a comment on a list.

Calls to this endpoint must include the access token for an authenticated member (see Authentication).

Parameters

id Required path string

The LID of the list.

Response

201

Success

ListComment
204

A comment with the same message already exists (no action was taken)

400

Bad request

401

There is no authenticated member

403

The authenticated member is not authorized to comment on this list

404

No list matches the specified ID

GET /list/{id}/entries

Get entries for a list by ID.

Parameters

id Required path string

The LID of the list.

cursor query string

The pagination cursor.

perPage query integer

The number of items to include per page (default is 20, maximum is 100).

filmId query
string[]

multiple parameters (filmId=aaa&filmId=bbb)

Specify up to 100 Letterboxd IDs or TMDB IDs prefixed with tmdb:, or IMDB IDs prefixed with imdb:

genre query string

Specify the LID of a genre to limit films to those within the specified genre.

includeGenre query
string[]

multiple parameters (includeGenre=aaa&includeGenre=bbb)

Specify the LID of up to 100 genres to limit films to those within all of the specified genres.

excludeGenre query
string[]

multiple parameters (excludeGenre=aaa&excludeGenre=bbb)

Specify the LID of up to 100 genres to limit films to those within none of the specified genres.

country query string

Specify the ISO 3166-1 defined code of the country to limit films to those produced in the specified country.

language query string

Specify the ISO 639-1 defined code of the language to limit films to those using the specified spoken language.

decade query integer

Specify the starting year of a decade (must end in 0) to limit films to those released during the decade.

year query integer

Specify a year to limit films to those released during that year.

service query string

Specify the ID of a supported service to limit films to those available from that service. The list of available services can be found by using the /films/film-services endpoint.

where query
enum[] ∈ {Released, NotReleased, InWatchlist, NotInWatchlist, Logged, NotLogged, Reviewed, NotReviewed, Owned, NotOwned, Rated, NotRated, Liked, NotLiked, WatchedFromWatchlist, Watched, NotWatched, FeatureLength, NotFeatureLength, Fiction, Film, TV}

multiple parameters (where=aaa&where=bbb)

Specify one or more values to limit the list of films accordingly.

member query string

Specify the LID of a member to limit the returned films according to the value set in memberRelationship or to access the MemberRating* sort options.

memberRelationship query enum ∈ {Ignore, Watched (default), NotWatched, Liked, NotLiked, Rated, NotRated, InWatchlist, NotInWatchlist, Favorited}

Must be used in conjunction with member. Defaults to Watched. Specify the type of relationship to limit the returned films accordingly. Use Ignore if you only intend to specify the member for use with sort=MemberRating*.

includeFriends query enum ∈ {None (default), All, Only}

Must be used in conjunction with member. Defaults to None, which only returns films from the member’s account. Use Only to return films from the member’s friends, and All to return films from both the member and their friends.

tag query string

DEPRECATED Use tagCode instead.

tagCode query string

Specify a tag code to limit the returned films to those tagged accordingly.

tagger query string

Must be used with tagCode. Specify the LID of a member to focus the tag filter on the member.

includeTaggerFriends query enum ∈ {None (default), All, Only}

Must be used in conjunction with tagger. Defaults to None, which filters tags set by the member. Use Only to filter tags set by the member’s friends, and All to filter tags set by both the member and their friends.

sort query enum ∈ {ListRanking (default), WhenAddedToList, FilmName, OwnerRatingHighToLow, OwnerRatingLowToHigh, AuthenticatedMemberRatingHighToLow, AuthenticatedMemberRatingLowToHigh, MemberRatingHighToLow, MemberRatingLowToHigh, AverageRatingHighToLow, AverageRatingLowToHigh, RatingHighToLow, RatingLowToHigh, ReleaseDateLatestFirst, ReleaseDateEarliestFirst, FilmDurationShortestFirst, FilmDurationLongestFirst, FilmPopularity, FilmPopularityThisWeek, FilmPopularityThisMonth, FilmPopularityThisYear}

The order in which the entries should be returned. Defaults to ListRanking, which is the order specified by the list owner.The AuthenticatedMember* values are only available to signed-in members.The MemberRating values must be used in conjunction with member and are only available when specifying a single member (i.e. IncludeFriends=None).DEPRECATED The FilmPopularityThisWeek, FilmPopularityThisMonth and FilmPopularityThisYear options are deprecated, and have never worked.
The Rating* options are deprecated in favor of AverageRating*.

Response

200

Success

ListEntriesResponse
404

No list matches the specified ID

GET /list/{id}/me

Get details of the authenticated member’s relationship with a list by ID.

Calls to this endpoint must include the access token for an authenticated member (see Authentication).

Parameters

id Required path string

The LID of the list.

Response

200

Success

ListRelationship
401

There is no authenticated member

404

No list matches the specified ID

PATCH /list/{id}/me

Update the authenticated member’s relationship with a list by ID.

Calls to this endpoint must include the access token for an authenticated member (see Authentication).

Parameters

id Required path string

The LID of the list.

Response

200

Success

ListRelationshipUpdateResponse
401

There is no authenticated member, or the authenticated member does not own the resource

404

No list matches the specified ID

POST /list/{id}/report

Report a list by ID.

Calls to this endpoint must include the access token for an authenticated member (see Authentication).

Parameters

id Required path string

The LID of the list.

Response

204

Success

401

There is no authenticated member

404

No list matches the specified ID

GET /list/{id}/statistics

Get statistical data about a list by ID.

Parameters

id Required path string

The LID of the list.

Response

200

Success

ListStatistics
404

No list matches the specified ID

GET /lists

A cursored window over a list of lists.

Use the ‘next’ cursor to move through the list.

Parameters

cursor query string

The pagination cursor.

perPage query integer

The number of items to include per page (default is 20, maximum is 100).

sort query enum ∈ {Date (default), WhenPublishedLatestFirst, WhenPublishedEarliestFirst, WhenCreatedLatestFirst, WhenCreatedEarliestFirst, ListName, ListPopularity, ListPopularityThisWeek, ListPopularityThisMonth, ListPopularityThisYear, ListPopularityWithFriends, ListPopularityWithFriendsThisWeek, ListPopularityWithFriendsThisMonth, ListPopularityWithFriendsThisYear}

Defaults to Date, which returns lists that were most recently created/updated first. The *WithFriends values are only available to signed-in members and consider popularity amongst the signed-in member’s friends.

film query string

Specify the LID of a film to return lists that include that film.

clonedFrom query string

Specify the LID of a list to return lists that were cloned from that list.

tag query string

DEPRECATED Use tagCode instead.

tagCode query string

Specify a tag code to limit the returned lists to those tagged accordingly.

tagger query string

Must be used with tagCode. Specify the LID of a member to focus the tag filter on the member.

includeTaggerFriends query enum ∈ {None (default), All, Only}

Must be used in conjunction with tagger. Defaults to None, which filters tags set by the member. Use Only to filter tags set by the member’s friends, and All to filter tags set by both the member and their friends.

member query string

Specify the LID of a member to return lists that are owned or liked by the member (or their friends, when used with includeFriends).

memberRelationship query enum ∈ {Owner (default), Liked}

Must be used in conjunction with member. Defaults to Owner, which returns lists owned by the specified member. Use Liked to return lists liked by the member.

includeFriends query enum ∈ {None (default), All, Only}

Must be used in conjunction with member. Defaults to None, which only returns lists from the member’s account. Use Only to return lists from the member’s friends, and All to return lists from both the member and their friends.

where query
enum[] ∈ {Clean, Published, NotPublished}

multiple parameters (where=aaa&where=bbb)

Specify Clean to return lists that do not contain profane language. Specify Published to return the member’s lists that have been made public. Note that unpublished lists for members other than the authenticated member are never returned. Specify NotPublished to return the authenticated member’s lists that have not been made public.

filter query
enum[] ∈ {NoDuplicateMembers}

multiple parameters (filter=aaa&filter=bbb)

Specify NoDuplicateMembers to limit the list to only the first list for each member. NoDuplicateMembers is only available when using these sort orders: Date, WhenPublishedLatestFirst, WhenCreatedLatestFirst.

filmsOfNote query
string[]

multiple parameters (filmsOfNote=aaa&filmsOfNote=bbb)

Specify the LIDs of any film(s) you wish to see the status for in respect of the returned list(s). For each nominated film, the response will indicate (for each returned list) whether the list contains the film, and if so, its rank position.

Response

200

Success

ListsResponse
400

Bad request

403

There is no authenticated member, or the authenticated member does not own the resource (when requesting where=NotPublished)

404

No film, member, tag or list matches the specified ID.

PATCH /lists

Add one or more films to one or more lists.

Calls to this endpoint must include the access token for an authenticated member (see Authentication).

Response

200

Success

ListAdditionResponse
400

Bad request

401

There is no authenticated member

POST /lists

Create a list.

Calls to this endpoint must include the access token for an authenticated member (see Authentication).

Response

200

Success

ListCreateResponse
400

Bad request

401

There is no authenticated member

GET /lists/topics

Get a list of featured topics/lists (e.g. for display in the Browse tab of our apps).

Response

200

Success

TopicsResponse

GET /log-entries

A cursored window over the log entries for a film or member. A log entry is either a diary entry (must have a date) or a review (must have review text). Log entries can be both a diary entry and a review if they satisfy both criteria.

Use the ‘next’ cursor to move through the list.

Parameters

cursor query string

The pagination cursor.

perPage query integer

The number of items to include per page (default is 20, maximum is 100).

sort query enum ∈ {WhenAdded (default), Date, DiaryCount, ReviewCount, WhenLiked, EntryRatingHighToLow, EntryRatingLowToHigh, RatingHighToLow, RatingLowToHigh, AuthenticatedMemberRatingHighToLow, AuthenticatedMemberRatingLowToHigh, MemberRatingHighToLow, MemberRatingLowToHigh, AverageRatingHighToLow, AverageRatingLowToHigh, ReleaseDateLatestFirst, ReleaseDateEarliestFirst, FilmName, FilmDurationShortestFirst, FilmDurationLongestFirst, ReviewPopularity, ReviewPopularityThisWeek, ReviewPopularityThisMonth, ReviewPopularityThisYear, ReviewPopularityWithFriends, ReviewPopularityWithFriendsThisWeek, ReviewPopularityWithFriendsThisMonth, ReviewPopularityWithFriendsThisYear, FilmPopularity, FilmPopularityThisWeek, FilmPopularityThisMonth, FilmPopularityThisYear, FilmPopularityWithFriends, FilmPopularityWithFriendsThisWeek, FilmPopularityWithFriendsThisMonth, FilmPopularityWithFriendsThisYear}

The order in which the log entries should be returned. Defaults to WhenAdded, which orders by creation date, unless you specify where=HasDiaryDate in which case the default is Date.The AuthenticatedMember* values are only available to signed-in members.The MemberRating values must be used in conjunction with member and are only available when specifying a single member (i.e. IncludeFriends=None).The ReviewPopularity values return reviews with more activity (likes/​comments) first, and imply where=HasReview.The FilmPopularity values return reviews for films with more combined activity first.The *WithFriends values are only available to signed-in members and consider popularity amongst the signed-in member’s friends.The Date value sorts by the diary date, and implies where=HasDiaryDateIf a film is specified, the only applicable sort orders are WhenAdded, Date, EntryRating* or ReviewPopularity*.DEPRECATED The Rating* options are deprecated in favor of EntryRating*.

film query string

Specify the LID of a film to return log entries for that film. Must not be included if the sort value is one of FilmName, ReleaseDate*, FilmDuration* or any of the FilmPopularity options.

member query string

Specify the LID of a member to limit the returned log entries according to the value set in memberRelationship or to access the MemberRating* sort options.

memberRelationship query enum ∈ {Ignore, Owner, Liked}

Must be used in conjunction with member. Use Owner to limit the returned log entries to those created by the specified member. Use Liked to limit the returned reviews to those liked by the specified member (implies where=HasReview).

filmMemberRelationship query enum ∈ {Ignore, Watched, NotWatched, Liked, NotLiked, Rated, NotRated, InWatchlist, NotInWatchlist, Favorited}

Must be used in conjunction with member. Specify the type of relationship to limit the returned films accordingly. e.g. Use Liked to limit the returned reviews to those for films liked by the member.

includeFriends query enum ∈ {None (default), All, Only}

Must be used in conjunction with member. Defaults to None, which only returns log entries created or liked by the member. Use Only to return log entries created or liked by the member’s friends, and All to return log entries created or liked by both the member and their friends.

year query integer

If set, limits the returned log entries to those with date that falls during the specified year.

month query integer

Accepts values of 1 through 12. Must be used with year. If set, limits the returned log entries to those with a date that falls during the specified month and year.

week query integer

Accepts values of 1 through 52. Must be used with year. If set, limits the returned log entries to those with a date that falls during the specified week and year.

day query integer

Accepts values of 1 through 31. Must be used with month and year. If set, limits the returned log entries to those with a date that falls on the specified day, month and year.

minRating query number

Allowable values are between 0.5 and 5.0, with increments of 0.5. If set, limits the returned log entries to those with a rating equal to or higher than the specified rating.

maxRating query number

Allowable values are between 0.5 and 5.0, with increments of 0.5. If set, limits the returned log entries to those with a rating equal to or lower than the specified rating.

filmDecade query integer

Specify the starting year of a decade (must end in 0) to limit films to those released during the decade.

filmYear query integer

Specify a year to limit films to those released during that year.

genre query string

The LID of the genre. If set, limits the returned log entries to those for films that match the specified genre.

includeGenre query
string[]

multiple parameters (includeGenre=aaa&includeGenre=bbb)

Specify the LID of up to 100 genres to limit the returned log entries to those for films within all of the specified genres.

excludeGenre query
string[]

multiple parameters (excludeGenre=aaa&excludeGenre=bbb)

Specify the LID of up to 100 genres to limit the returned log entries to those for films within none of the specified genres.

country query string

Specify the ISO 3166-1 defined code of the country to limit films to those produced in the specified country.

language query string

Specify the ISO 639-1 defined code of the language to limit films to those using the specified spoken language.

tag query string

DEPRECATED Use tagCode instead.

tagCode query string

Specify a tag code to limit the returned log entries to those tagged accordingly.

tagger query string

Must be used with tagCode. Specify the LID of a member to focus the tag filter on the member.

includeTaggerFriends query enum ∈ {None (default), All, Only}

Must be used in conjunction with tagger. Defaults to None, which filters tags set by the member. Use Only to filter tags set by the member’s friends, and All to filter tags set by both the member and their friends.

service query string

Specify the ID of a supported service to limit films to those available from that service. The list of available services can be found by using the /films/film-services endpoint.

where query
enum[] ∈ {HasDiaryDate, HasReview, Clean, NoSpoilers, Released, NotReleased, FeatureLength, NotFeatureLength, InWatchlist, NotInWatchlist, Watched, NotWatched, Rated, NotRated, Logged, NotLogged, Reviewed, NotReviewed, Owned, NotOwned, Liked, NotLiked, Fiction, Film, TV}

multiple parameters (where=aaa&where=bbb)

Specify one or more values to limit the returned log entries accordingly. Released, NotReleased, FeatureLength and NotFeatureLength refer to properties of the associated film rather than to the relevant log entry. Use InWatchlist or NotInWatchlist to limit the returned log entries based on the contents of the authenticated member’s watchlist. Use Watched and NotWatched to limit the returned log entries based on the authenticated member’s list of watched films. (Note: you can specify member and filmMemberRelationship to further limit returned entries based on another member’s films or watchlist.) Use HasDiaryDate to limit the returned log entries to those that appear in a member’s diary. Use HasReview to limit the returned log entries to those containing a review. Use Clean to exclude reviews that contain profane language. Use NoSpoilers to exclude reviews where the owner has indicated that the review text contains plot spoilers for the film. Use Rated to limit the returned log entries to those that have a rating (use minRating and maxRating for more control). Use NotRated to limit the returned log entries to those that do not have a rating. Use Fiction to exclude log entries of documentaries. Use Film to exclude log entries of tv shows. Use TV to only return log entries of tv shows.

filter query
enum[] ∈ {NoDuplicateMembers}

multiple parameters (filter=aaa&filter=bbb)

Specify NoDuplicateMembers to return only the first log entry for each member. If film is not provided, only recent Log Entries will be returned (i.e. entries logged in the past 30 days). NoDuplicateMembers is only available when using these sort orders: WhenAdded, Date, ReviewPopularity*. You may not use NoDuplicateMembers with filmMemberRelationship, filmDecade, filmYear, genre, tagCode, service, or where except HasDiaryDate, HasReview, Clean, and/or NoSpoilers.

Response

200

Success

LogEntriesResponse
404

Film or Member not found

POST /log-entries

Create a log entry. A log entry is either a diary entry (must have a date) or a review (must have review text). Log entries can be both a diary entry and a review if they satisfy both criteria.

Calls to this endpoint must include the access token for an authenticated member (see Authentication).

Response

201

Success

LogEntry
204

No action was taken, as the log entry already exists

400

Bad request

401

There is no authenticated member

404

The film was not found

DELETE /log-entry/{id}

Delete a log entry by ID.

Calls to this endpoint must include the access token for an authenticated member (see Authentication).

Parameters

id Required path string

The LID of the log entry.

Response

204

Success

400

Bad request

401

There is no authenticated member

403

The authenticated member is not authorized to delete this log entry

404

No log entry matches the specified ID

GET /log-entry/{id}

Get details about a log entry by ID.

Parameters

id Required path string

The LID of the log entry.

Response

200

Success

LogEntry
404

No log entry matches the specified ID

PATCH /log-entry/{id}

Update a log entry by ID.

Calls to this endpoint must include the access token for an authenticated member (see Authentication).

Parameters

id Required path string

The LID of the log entry.

Response

200

Success

ReviewUpdateResponse
400

Bad request

401

There is no authenticated member, or the authenticated member does not own the resource

404

No log entry matches the specified ID

GET /log-entry/{id}/comments

A cursored window over the comments for a log entry’s review.

Use the ‘next’ cursor to move through the comments.

Parameters

id Required path string

The LID of the log entry.

cursor query string

The pagination cursor.

perPage query integer

The number of items to include per page (default is 20, maximum is 100).

sort query enum ∈ {Date, DateLatestFirst, Updates}

Defaults to Date. The Updates sort order returns newest content first. Use this to get the most recently posted or edited comments, and pass includeDeletions=true to remain consistent in the case where a comment has been deleted.

includeDeletions query boolean

Use this to discover any comments that were deleted.

Response

200

Success

ReviewCommentsResponse
404

No log entry matches the specified ID

POST /log-entry/{id}/comments

Create a comment on a review.

Calls to this endpoint must include the access token for an authenticated member (see Authentication).

Parameters

id Required path string

The LID of the log entry.

Response

201

Success

ReviewComment
204

A comment with the same message already exists (no action was taken)

400

Bad request

401

There is no authenticated member

403

The authenticated member is not authorized to comment on this review

404

No film matches the specified ID

GET /log-entry/{id}/me

Get details of the authenticated member’s relationship with a log entry’s review by ID.

Calls to this endpoint must include the access token for an authenticated member (see Authentication).

Parameters

id Required path string

The LID of the log entry.

Response

200

Success

ReviewRelationship
401

There is no authenticated member

404

No log entry matches the specified ID

PATCH /log-entry/{id}/me

Update the authenticated member’s relationship with a log entry’s review by ID.

Calls to this endpoint must include the access token for an authenticated member (see Authentication).

Parameters

id Required path string

The LID of the log entry.

Response

200

Success

ReviewRelationshipUpdateResponse
401

There is no authenticated member

403

The authenticated member is not authorized to like or subscribe to this review

404

No log entry matches the specified ID

POST /log-entry/{id}/report

Report a log entry’s review by ID.

Calls to this endpoint must include the access token for an authenticated member (see Authentication).

Parameters

id Required path string

The LID of the log entry.

Response

204

Success

401

There is no authenticated member

404

No log entry matches the specified ID

GET /log-entry/{id}/statistics

Get statistical data about a log-entry’s review by ID.

Parameters

id Required path string

The LID of the log entry.

Response

200

Success

ReviewStatistics
404

No log entry matches the specified ID

GET /me

Get details about the authenticated member.

Calls to this endpoint must include the access token for an authenticated member (see Authentication).

Response

200

Success

MemberAccount
401

There is no authenticated member

PATCH /me

Update the profile settings for the authenticated member.

Calls to this endpoint must include the access token for an authenticated member (see Authentication).

Response

200

Success

MemberSettingsUpdateResponse
400

Bad request

401

There is no authenticated member

POST /me/deregister-push-notifications

Deregister a device so it no longer receives push notifications.

Calls to this endpoint must include the access token for an authenticated member (see Authentication).

Response

204

Success

401

There is no authenticated member

POST /me/disable

Deactivate account.

Calls to this endpoint must include the access token for an authenticated member (see Authentication).

Response

204

Success

401

There is no authenticated member

POST /me/register-push-notifications

Register a device so it can receive push notifications. Letterboxd uses Firebase to send notifications, so the token provided must be obtained from Firebase.

Calls to this endpoint must include the access token for an authenticated member (see Authentication).

Response

204

Success

401

There is no authenticated member

POST /me/validation-request

Request a validation link via email.

Calls to this endpoint must include the access token for an authenticated member (see Authentication). If the email address associated with a member’s account has not been validated and the validation link has expired or been lost, use this endpoint to request a new validation link.

Response

204

Success (the email was dispatched if it matched an existing account)

401

There is no authenticated member

403

The authenticated member’s email address was already successfully validated

429

Too many validation requests have been made (the email is probably in the member’s spam or junk folder)

GET /member/{id}

Get details about a member by ID.

Parameters

id Required path string

The LID of the member.

Response

200

Success

Member
404

No member matches the specified ID, or the member has opted out of appearing in the API

GET /member/{id}/activity

A cursored window over the activity for a member.

Use the ‘next’ cursor to move through the list.

Parameters

id Required path string

The LID of the member.

cursor query string

The pagination cursor.

perPage query integer

The number of items to include per page (default is 20, maximum is 100).

include query
enum[] ∈ {ReviewActivity, ReviewCommentActivity, ReviewLikeActivity, ListActivity, ListCommentActivity, ListLikeActivity, StoryActivity, DiaryEntryActivity, FilmRatingActivity, FilmWatchActivity, FilmLikeActivity, WatchlistActivity, FollowActivity, RegistrationActivity, InvitationAcceptedActivity}

multiple parameters (include=aaa&include=bbb)

Only supported for paying members.Use include to specify the subset of activity to be returned. If neither include nor exclude is set, the activity types included depend on the where parameter:If where=OwnActivity is specified, all activity except FilmLikeActivity, FilmWatchActivity and InvitationAcceptedActivity is included.Otherwise all activity except FilmLikeActivity, FilmWatchActivity, FilmRatingActivity, FollowActivity, RegistrationActivity and InvitationAcceptedActivity is included.These defaults mimic those shown on the website.

exclude query
enum[] ∈ {ReviewActivity, ReviewCommentActivity, ReviewLikeActivity, ListActivity, ListCommentActivity, ListLikeActivity, StoryActivity, DiaryEntryActivity, FilmRatingActivity, FilmWatchActivity, FilmLikeActivity, WatchlistActivity, FollowActivity, RegistrationActivity, InvitationAcceptedActivity}

multiple parameters (exclude=aaa&exclude=bbb)

Only supported for paying members.DEPRECATED Use include instead.

where query
enum[] ∈ {OwnActivity, NotOwnActivity, IncomingActivity, NotIncomingActivity, NetworkActivity}

multiple parameters (where=aaa&where=bbb)

Use where to reduce the subset of activity to be returned. If where is not set, all default activity types relating to the member are returned. If multiple values are supplied, only activity matching all terms will be returned, e.g. where=OwnActivity&where=NotIncomingActivity will return all activity by the member except their comments on their own lists and reviews. NetworkActivity is activity performed either by the member or their followers. Use where=NetworkActivity&where=NotOwnActivity to only see activity from followers. If you don’t specify any of NetworkActivity, OwnActivity or NotIncomingActivity, you will receive activity related to the member’s content from members outside their network (e.g. comments and likes on the member’s lists and reviews).

adult query boolean

Whether to include activity related to adult content. Default to false.

Response

200

Success

ActivityResponse
404

No member matches the specified ID, or the member has opted out of appearing in the API

GET /member/{id}/list-tags

DEPRECATED Please use /list-tags-2 instead. Get the list of a member’s tags, or those that match an optional search prefix.

The tags will be returned in order of relevance. All tags previously used by the member will be returned if no search prefix is specified.

Parameters

id Required path string

The LID of the member.

input query string

A case-insensitive prefix match. E.g. “pro” will match “pro”, “project” and “Professional”. An empty input will match all tags.

Response

200

Success

TagsResponse
404

No member matches the specified ID, or the member has opted out of appearing in the API

GET /member/{id}/list-tags-2

Get the list of a member’s tags, or those that match an optional search prefix.

The tags will be returned in order of relevance. All tags previously used by the member will be returned if no search prefix is specified.

Parameters

id Required path string

The LID of the member.

input query string

A case-insensitive prefix match. E.g. “pro” will match “pro”, “project” and “Professional”. An empty input will match all tags.

Response

200

Success

MemberTagsResponse
404

No member matches the specified ID, or the member has opted out of appearing in the API

GET /member/{id}/log-entry-tags

Get the list of a member’s tags, or those that match an optional search prefix.

The tags will be returned in order of relevance. All tags previously used by the member will be returned if no search prefix is specified.

Parameters

id Required path string

The LID of the member.

input query string

A case-insensitive prefix match. E.g. “pro” will match “pro”, “project” and “Professional”. An empty input will match all tags.

Response

200

Success

MemberTagsResponse
404

No member matches the specified ID, or the member has opted out of appearing in the API

GET /member/{id}/me

Get details of the authenticated member’s relationship with another member by ID.

Calls to this endpoint must include the access token for an authenticated member (see Authentication).

Parameters

id Required path string

The LID of the other member.

Response

200

Success

MemberRelationship
401

There is no authenticated member

404

No member matches the specified ID, or the member has opted out of appearing in the API

PATCH /member/{id}/me

Update the authenticated member’s relationship with another member by ID.

Calls to this endpoint must include the access token for an authenticated member (see Authentication).

Parameters

id Required path string

The LID of the other member.

Response

200

Success

MemberRelationshipUpdateResponse
401

There is no authenticated member

404

No member matches the specified ID, or the member has opted out of appearing in the API

POST /member/{id}/report

Report a member by ID.

Calls to this endpoint must include the access token for an authenticated member (see Authentication).

Parameters

id Required path string

The LID of the member.

Response

204

Success

401

There is no authenticated member

404

No member matches the specified ID, or the member has opted out of appearing in the API

GET /member/{id}/review-tags

DEPRECATED Please use /log-entry-tags

Parameters

id Required path string

The LID of the member.

input query string

A case-insensitive prefix match. E.g. “pro” will match “pro”, “project” and “Professional”. An empty input will match all tags.

Response

200

Success

TagsResponse
404

No member matches the specified ID, or the member has opted out of appearing in the API

GET /member/{id}/review-tags-2

DEPRECATED Please use /log-entry-tags instead

Parameters

id Required path string

The LID of the member.

input query string

A case-insensitive prefix match. E.g. “pro” will match “pro”, “project” and “Professional”. An empty input will match all tags.

Response

200

Success

MemberTagsResponse
404

No member matches the specified ID, or the member has opted out of appearing in the API

GET /member/{id}/statistics

Get statistical data about a member by ID.

Parameters

id Required path string

The LID of the member.

Response

200

Success

MemberStatistics
404

No member matches the specified ID, or the member has opted out of appearing in the API

GET /member/{id}/watchlist

Get details of a member’s public watchlist by ID.

The response will include the film relationships for the signed-in member, the watchlist’s owner, and the member indicated by the member LID if specified (the member and memberRelationship parameters are optional, and can be used to perform comparisons between the watchlist owner and another member). Use the /film/{id}/me endpoint to add or remove films from a member’s watchlist.

Parameters

id Required path string

The LID of the member.

cursor query string

The pagination cursor.

perPage query integer

The number of items to include per page (default is 20, maximum is 100).

filmId query
string[]

multiple parameters (filmId=aaa&filmId=bbb)

Specify up to 100 Letterboxd IDs or TMDB IDs prefixed with tmdb:, or IMDB IDs prefixed with imdb:

genre query string

Specify the LID of a genre to limit films to those within the specified genre.

includeGenre query
string[]

multiple parameters (includeGenre=aaa&includeGenre=bbb)

Specify the LID of up to 100 genres to limit films to those within all of the specified genres.

excludeGenre query
string[]

multiple parameters (excludeGenre=aaa&excludeGenre=bbb)

Specify the LID of up to 100 genres to limit films to those within none of the specified genres.

country query string

Specify the ISO 3166-1 defined code of the country to limit films to those produced in the specified country.

language query string

Specify the ISO 639-1 defined code of the language to limit films to those using the specified spoken language.

decade query integer

Specify the starting year of a decade (must end in 0) to limit films to those released during the decade.

year query integer

Specify a year to limit films to those released during that year.

service query string

Specify the ID of a supported service to limit films to those available from that service. The list of available services can be found by using the /films/film-services endpoint.

where query
enum[] ∈ {Released, NotReleased, InWatchlist, NotInWatchlist, Logged, NotLogged, Reviewed, NotReviewed, Owned, NotOwned, Rated, NotRated, Liked, NotLiked, WatchedFromWatchlist, Watched, NotWatched, FeatureLength, NotFeatureLength, Fiction, Film, TV}

multiple parameters (where=aaa&where=bbb)

Specify one or more values to limit the list of films accordingly.

member query string

Specify the LID of a member to limit the returned films according to the value set in memberRelationship or to access the MemberRating* sort options.

memberRelationship query enum ∈ {Ignore, Watched (default), NotWatched, Liked, NotLiked, Rated, NotRated, InWatchlist, NotInWatchlist, Favorited}

Must be used in conjunction with member. Defaults to Watched. Specify the type of relationship to limit the returned films accordingly. Use Ignore if you only intend to specify the member for use with sort=MemberRating*.

includeFriends query enum ∈ {None (default), All, Only}

Must be used in conjunction with member. Defaults to None, which only returns films from the member’s account. Use Only to return films from the member’s friends, and All to return films from both the member and their friends.

tag query string

DEPRECATED Use tagCode instead.

tagCode query string

Specify a tag code to limit the returned films to those tagged accordingly.

tagger query string

Must be used with tagCode. Specify the LID of a member to focus the tag filter on the member.

includeTaggerFriends query enum ∈ {None (default), All, Only}

Must be used in conjunction with tagger. Defaults to None, which filters tags set by the member. Use Only to filter tags set by the member’s friends, and All to filter tags set by both the member and their friends.

sort query enum ∈ {Added (default), DateLatestFirst, DateEarliestFirst, Shuffle, FilmName, OwnerRatingHighToLow, OwnerRatingLowToHigh, AuthenticatedMemberRatingHighToLow, AuthenticatedMemberRatingLowToHigh, MemberRatingHighToLow, MemberRatingLowToHigh, AverageRatingHighToLow, AverageRatingLowToHigh, ReleaseDateLatestFirst, ReleaseDateEarliestFirst, FilmDurationShortestFirst, FilmDurationLongestFirst, FilmPopularity, RatingHighToLow, RatingLowToHigh, FilmPopularityThisWeek, FilmPopularityThisMonth, FilmPopularityThisYear}

The order in which the entries should be returned. Defaults to Added, which is the order that the films were added to the watchlist, most recent first.The AuthenticatedMember* values are only available to signed-in members.The MemberRating values must be used in conjunction with member and are only available when specifying a single member (i.e. IncludeFriends=None).DEPRECATED The FilmPopularityThisWeek, FilmPopularityThisMonth and FilmPopularityThisYear options are deprecated, and have never worked.
The Rating* options are deprecated in favor of AverageRating*.

Response

200

Success

FilmsResponse
403

The specified member’s watchlist is private

404

No member matches the specified ID, or the member has opted out of appearing in the API

GET /members

A cursored window over the list of members.

Use the ‘next’ cursor to move through the list.

Parameters

cursor query string

The pagination cursor.

perPage query integer

The number of items to include per page (default is 20, maximum is 100).

sort query enum ∈ {Date (default), Name, MemberPopularity, MemberPopularityThisWeek, MemberPopularityThisMonth, MemberPopularityThisYear, MemberPopularityWithFriends, MemberPopularityWithFriendsThisWeek, MemberPopularityWithFriendsThisMonth, MemberPopularityWithFriendsThisYear}

Defaults to Date, which has different semantics based on the request:When review is specified, members who most recently liked the review appear first.When list is specified, members who most recently liked the list appear first.When film is specified and filmRelationship=Watched, members who most recently watched the film appear first.When film is specified and filmRelationship=Liked, members who most recently liked the film appear first.When film is specified and filmRelationship=InWatchlist, members who most recently added the film to their watchlist appear first.When member is specified and memberRelationship=IsFollowing, most recently followed members appear first.When member is specified and memberRelationship=IsFollowedBy, most recent followers appear first.Otherwise, members who most recently joined the site appear first.The *WithFriends values are only available to authenticated members and consider popularity amongst the member’s friends.

member query string

Specify the LID of a member to return members who follow or are followed by that member.

memberRelationship query enum ∈ {IsFollowing (default), IsFollowedBy}

Must be used in conjunction with member. Defaults to IsFollowing, which returns the list of members followed by the member. Use IsFollowedBy to return the list of members that follow the member.

film query string

Specify the LID of a film to return members who have interacted with that film.

filmRelationship query enum ∈ {Ignore, Watched (default), NotWatched, Liked, NotLiked, Rated, NotRated, InWatchlist, NotInWatchlist, Favorited}

Must be used in conjunction with film. Defaults to Watched, which returns the list of members who have seen the film. Specify the type of relationship to limit the returned members accordingly. You must specify a member in order to use the InWatchlist relationship.

list query string

Specify the LID of a list to return members who like that list.

review query string

Specify the LID of a review to return members who like that review.

Response

200

Success

MembersResponse

GET /members/pronouns

Get a list of pronouns supported by the PATCH /me endpoint.

Response

200

Success

PronounsResponse

POST /members/register

Create a new account.

Use this endpoint to register a new member account with the Letterboxd network. Usernames must be between 2 and 15 characters long and may only contain upper or lowercase letters, numbers or the underscore (_) character.

Request

RegisterRequest

Response

201

Success

Member
400

The username was already taken or is invalid.

GET /news

Get recent news from the Letterboxd editors.

Parameters

cursor query string

The pagination cursor.

perPage query integer

The number of items to include per page (default is 20, maximum is 100).

Response

200

Success

NewsResponse

GET /search

Parameters

cursor query string

The pagination cursor.

perPage query integer

The number of items to include per page (default is 20, maximum is 100).

input Required query string

The word, partial word or phrase to search for.

searchMethod query enum ∈ {FullText (default), Autocomplete}

The type of search to perform. Defaults to FullText, which performs a standard search considering text in all fields. Autocomplete only searches primary fields.

include query
enum[] ∈ {ContributorSearchItem, FilmSearchItem, ListSearchItem, MemberSearchItem, ReviewSearchItem, TagSearchItem}

multiple parameters (include=aaa&include=bbb)

The types of results to search for. Default to all SearchResultTypes.

contributionType query enum ∈ {Director, CoDirector, Actor, Producer, Writer, Editor, Cinematography, ProductionDesign, ArtDirection, SetDecoration, VisualEffects, Composer, Sound, Costumes, MakeUp, Studio}

The type of contributor to search for. Implies include=ContributorSearchItem.

adult query boolean

Whether to include adult content in search results. Default to false.

Response

200

successful operation

SearchResponse

GET /stories

A cursored window over a list of stories.

Use the ‘next’ cursor to move through the list.

Parameters

cursor query string

The pagination cursor.

perPage query integer

The number of items to include per page (default is 20, maximum is 100).

sort query enum ∈ {WhenUpdatedLatestFirst (default), WhenUpdatedEarliestFirst, WhenPublishedLatestFirst, WhenPublishedEarliestFirst, WhenCreatedLatestFirst, WhenCreatedEarliestFirst, StoryTitle}

Defaults to WhenUpdatedLatestFirst, which returns stories that were most recently created/​updated first.

member query string

Specify the LID of a member to return stories that are owned by the member.

where query
enum[] ∈ {Published, NotPublished}

multiple parameters (where=aaa&where=bbb)

Specify Published to return the member’s stories that have been made public. Note that unpublished stories for members other than the authenticated member are never returned. Specify NotPublished to return the authenticated member’s stories that have not been made public.

Response

200

Success

StoriesResponse
400

Bad request

404

No film, member, tag or list matches the specified ID.

GET /story/{id}

Get details of a story by ID.

Parameters

id Required path string

The LID of the story.

Response

200

Success

Story
404

No story matches the specified ID

Definitions

AbstractActivity

Properties

type Discriminator

The type of activity.

member MemberSummary

The member associated with the activity.

whenCreated string

The timestamp of the activity, in ISO 8601 format with UTC timezone, i.e. YYYY-MM-DDThh:mm:ssZ

"1997-08-29T07:14:00Z"

AbstractComment

Properties

type Discriminator
enum[] ∈ {ListComment, ReviewComment}

The type of comment.

id string

The LID of the comment/​reply.

member MemberSummary

The member who posted the comment.

whenCreated string

ISO 8601 format with UTC timezone, i.e. YYYY-MM-DDThh:mm:ssZ

"1997-08-29T07:14:00Z"
whenUpdated string

ISO 8601 format with UTC timezone, i.e. YYYY-MM-DDThh:mm:ssZ

"1997-08-29T07:14:00Z"
commentLbml string

The message portion of the comment in LBML. May contain the following HTML tags: <br> <strong> <em> <b> <i> <a href=""> <blockquote>.

removedByAdmin boolean

If Letterboxd moderators have removed the comment from the site, removedByAdmin will be true and comment will not be included.

removedByContentOwner boolean

If the content owner has removed the comment from the site, removedByContentOwner will be true and comment will not be included.

deleted boolean

If the comment owner has removed the comment from the site, deleted will be true and comment will not be included.

blocked boolean

If the authenticated member has blocked the commenter, blocked will be true and comment will not be included.

blockedByOwner boolean

If the content owner has blocked the commenter, blockedByOwner will be true and comment will not be included.

editableWindowExpiresIn integer

If the authenticated member posted this comment, and the comment is still editable, this value shows the number of seconds remaining until the editing window closes.

comment string

The message portion of the comment formatted as HTML.

AbstractSearchItem

Properties

type Discriminator

The type of the search result.

score number

A relevancy value that can be used to order results.

AccessToken

Properties

access_token string

The access token that grants the member access. Combine this with the token_type to form the Authorization header.

token_type string

The type of the access token. Use value: bearer

refresh_token string

The refresh token is used to obtain a new access token, after the access token expires, without needing to prompt the member for their credentials again. The refresh token only expires if it is explicitly invalidated by Letterboxd, in which case the member should be prompted for their credentials (or stored credentials used).

expires_in integer

The number of seconds before the access token expires.

issuer string

ActivityResponse

Properties

next Cursor

The cursor to the next page of results.

items

The list of activity items.

AListAddition

Properties

list ListIdentifier

The list.

additions integer

The number of films added to the list.

AListEntryOccurrence

Properties

rank integer

If the list is ranked, this is the entry’s rank in the list, numbered from 1.

filmId string

The film LID for this entry.

AListTopic

Properties

name string

The topic name.

items

The list of featured lists for the topic.

AppleIAPSubscription

Properties

subscriptionDaysRemaining integer

The number of days until the subscription ends. Only included if the subscription is current. May be 0, in which case the subscription is current but will end today.

AppleIAPSubscriptionMessage

Properties

type enum ∈ {Error, Success}

The type of message.

code enum ∈ {SubscriptionAlreadyExpired, SubscriptionBelongsToAnotherMember, UnexpectedError}

The error message code.

title string

The error message text in human-readable form.

AppleIAPSubscriptionRequest

Properties

receiptToken Required string

The receipt token (Base-64 encoded).

AppleIAPSubscriptionResponse

Properties

data Required AppleIAPSubscription

The response object.

messages Required

A list of messages the API client should show to the user.

CommentCreationRequest

Properties

comment Required string

The message portion of the comment in LBML. May contain the following HTML tags: <br> <strong> <em> <b> <i> <a href=""> <blockquote>. This field has a maximum size of 100,000 characters.

CommentUpdateMessage

Properties

type enum ∈ {Error, Success}

The type of message.

code enum ∈ {MissingComment, CommentOnContentYouBlocked, CommentOnBlockedContent, CommentBan, CommentEditWindowExpired, CommentTooLong}

The error message code.

title string

The error message text in human-readable form.

CommentUpdateRequest

Properties

comment Required string

The message portion of the comment in LBML. May contain the following HTML tags: <br> <strong> <em> <b> <i> <a href=""> <blockquote>. This field has a maximum size of 100,000 characters.

CommentUpdateResponse

Properties

data Required AbstractComment

The response object.

messages Required

A list of messages the API client should show to the user.

ContributionStatistics

Properties

type enum ∈ {Director, CoDirector, Actor, Producer, Writer, Editor, Cinematography, ProductionDesign, ArtDirection, SetDecoration, VisualEffects, Composer, Sound, Costumes, MakeUp, Studio}

The type of contribution.

filmCount integer

The number of films for this contribution type.

Contributor

Properties

id string

The LID of the contributor.

name string

The name of the contributor.

tmdbid string

The ID of the contributor on TMDB, if known

statistics ContributorStatistics

An array of the types of contributions made, with a count of films for each contribution type.

links

A list of relevant URLs for this entity, on Letterboxd and external sites.

ContributorSearchItem < AbstractSearchItem

Inherited Properties

score Inherited number

A relevancy value that can be used to order results.

Properties

contributor Contributor

Details of the contributor.

ContributorStatistics

Properties

contributions

The statistics for each contribution type.

ContributorSummary

Properties

id string

The LID of the contributor.

name string

The name of the contributor.

characterName string

The character name if available (only if the contribution is as an Actor; see the type field in FilmContributions).

tmdbid string

The ID of the contributor on TMDB, if known

CountriesResponse

Properties

items

The list of countries.

Country

Properties

code string

The ISO 3166-1 defined code of the country.

name string

The name of the country.

Cursor

A cursor is a string value provided by the API. It should be treated as an opaque value — don’t change it.

DeregisterPushNotificationsRequest

Properties

deviceId Required string

The device ID.

DiaryDetails

Properties

diaryDate string

The date the film was watched, if specified, in ISO 8601 format, i.e. YYYY-MM-DD

rewatch boolean

Will be true if the member has indicated (or it can be otherwise determined) that the member has seen the film prior to this date.

DiaryEntryActivity < AbstractActivity

Inherited Properties

member Inherited MemberSummary

The member associated with the activity.

whenCreated Inherited string

The timestamp of the activity, in ISO 8601 format with UTC timezone, i.e. YYYY-MM-DDThh:mm:ssZ

"1997-08-29T07:14:00Z"

Properties

diaryEntry LogEntry

The log entry associated with this activity

DisableAccountRequest

Properties

currentPassword Required string

The member’s current password.

Film

Properties

id string

The LID of the film.

name string

The title of the film.

originalName string

The original title of the film, if it was first released with a non-English title.

alternativeNames
string[]

The other names by which the film is known (including alternative titles and/or foreign translations).

releaseYear integer

The year in which the film was first released.

directors

The list of directors for the film.

poster Image

The film’s poster image (2:3 aspect ratio in multiple sizes). Will contain only a single obfuscated image if the adult flag is true.

adultPoster Image

The film’s unobfuscated poster image (2:3 aspect ratio in multiple sizes), only populated if the adult flag is true, may contain adult content.

top250Position integer

The film’s position in the official Letterboxd Top 250 list of narrative feature films, null if the film is not in the list.

adult boolean

true if the film is in TMDb’s ‘Adult’ category.

filmCollectionId string

The LID of the collection containing this film.

links

A list of relevant URLs for this entity, on Letterboxd and external sites.

relationships

Relationships to the film for the authenticated member (if any) and other members where relevant.

tagline string

The tagline for the film.

description string

A synopsis of the film.

runTime integer

The film’s duration (in minutes).

backdrop Image

The film’s backdrop image (16:9 ratio in multiple sizes).

backdropFocalPoint number

The backdrop’s vertical focal point, expressed as a proportion of the image’s height, using values between 0.0 and 1.0. Use when cropping the image into a shorter space, such as in the page for a film on the Letterboxd site.

trailer FilmTrailer

The film’s trailer.

genres

The film’s genres.

countries

The film’s production countries.

languages

The film’s spoken languages.

contributions

The film’s contributors (director, cast and crew) grouped by discipline.

news

The related news items for the film.

recentStories

The related recent stories for a film.

FilmAvailability

Properties

service enum ∈ {Amazon, AmazonVideo, AmazonPrime, iTunes, Netflix}

DEPRECATED Use displayName instead.

displayName string

The name of the service.

icon string

The URL of the thumbnail image for the service.

country enum ∈ {AIA, ARE, ARG, ARM, ATG, AUS, AUT, AZE, BEL, BFA, BGR, BHR, BHS, BLR, BLZ, BMU, BOL, BRA, BRB, BRN, BWA, CAN, CHE, CHL, CHN, COL, CPV, CRI, CYM, CYP, CZE, DEU, DMA, DNK, DOM, ECU, EGY, ESP, EST, FIN, FJI, FRA, FSM, GBR, GHA, GMB, GNB, GRC, GRD, GTM, HKG, HND, HUN, IDN, IND, IRL, ISR, ITA, JOR, JPN, KAZ, KEN, KGZ, KHM, KNA, KOR, LAO, LBN, LKA, LTU, LUX, LVA, MAC, MDA, MEX, MLT, MNG, MOZ, MUS, MYS, NAM, NER, NGA, NIC, NLD, NOR, NPL, NZL, OMN, PAN, PER, PHL, PNG, POL, PRT, PRY, QAT, ROU, RUS, SAU, SGP, SLV, SVK, SVN, SWE, SWZ, THA, TJK, TKM, TTO, TUR, TWN, UGA, UKR, USA, UZB, VEN, VGB, VNM, ZAF, ZWE}

The regional store for the service. Not all countries are supported on all services.

id string

The unique ID (if any) for the film on this service.

url string

The URL for the film on this service.

types
string[]

The types of the availability, possible options included buy, rent and stream

FilmAvailabilityResponse

Properties

items

The list of stores where the film is available for streaming or purchasing, in order of preference. If the member has not specified their preferred stores for a service, the USA store will be assumed.

FilmCollection

Properties

id string

The LID of the film collection.

name string

The name of the collection.

films

The list of films in the collection.

links

A list of relevant URLs for this entity, on Letterboxd and external sites.

FilmContribution

Properties

type enum ∈ {Director, CoDirector, Actor, Producer, Writer, Editor, Cinematography, ProductionDesign, ArtDirection, SetDecoration, VisualEffects, Composer, Sound, Costumes, MakeUp, Studio}

The type of contribution.

film FilmSummary

The film.

characterName string

The name of the character (only when type is Actor).

FilmContributions

Properties

type enum ∈ {Director, CoDirector, Actor, Producer, Writer, Editor, Cinematography, ProductionDesign, ArtDirection, SetDecoration, VisualEffects, Composer, Sound, Costumes, MakeUp, Studio}

The type of contribution.

contributors

The list of contributors of the specified type for the film.

FilmContributionsCollection

Properties

contributions

The film’s contributors (director, cast and crew) grouped by discipline.

FilmContributionsResponse

Properties

next Cursor

The cursor to the next page of results.

items

The list of contributions.

metadata

Metadata about the contributor’s contributions.

relationships

The relationships to the contributor for the members referenced in the request.

FilmContributorMemberRelationship

Properties

member MemberSummary

The member.

relationships

The relationship details.

FilmContributorMetadata

Properties

type enum ∈ {Director, CoDirector, Actor, Producer, Writer, Editor, Cinematography, ProductionDesign, ArtDirection, SetDecoration, VisualEffects, Composer, Sound, Costumes, MakeUp, Studio}

The type of contribution.

data FilmsMetadata

The details for this contribution type.

FilmContributorRelationship

Properties

type enum ∈ {Director, CoDirector, Actor, Producer, Writer, Editor, Cinematography, ProductionDesign, ArtDirection, SetDecoration, VisualEffects, Composer, Sound, Costumes, MakeUp, Studio}

The type of contribution.

relationship FilmsRelationship

The relationship the member has with the (filtered) films.

FilmIdentifier

Properties

id string

The LID of the film.

FilmLikeActivity < AbstractActivity

Inherited Properties

member Inherited MemberSummary

The member associated with the activity.

whenCreated Inherited string

The timestamp of the activity, in ISO 8601 format with UTC timezone, i.e. YYYY-MM-DDThh:mm:ssZ

"1997-08-29T07:14:00Z"

Properties

film FilmSummary

The film associated with the activity. Includes a MemberFilmRelationship for the member who added the activity.

FilmRatingActivity < AbstractActivity

Inherited Properties

member Inherited MemberSummary

The member associated with the activity.

whenCreated Inherited string

The timestamp of the activity, in ISO 8601 format with UTC timezone, i.e. YYYY-MM-DDThh:mm:ssZ

"1997-08-29T07:14:00Z"

Properties

film FilmSummary

The film associated with the activity. Includes a MemberFilmRelationship for the member who added the activity.

rating number

The member’s rating for the film. Allowable values are between 0.5 and 5.0, with increments of 0.5.

FilmRelationship

Properties

watched boolean

Will be true if the member has indicated they’ve seen the film (via the ‘eye’ icon) or has a log entry for the film.

whenWatched string

If watched=true, whenWatched will contain the time when the member marked the film as watched. ISO 8601 format with UTC timezone, i.e. YYYY-MM-DDThh:mm:ssZ

liked boolean

Will be true if the member likes the film (via the ‘heart’ icon).

whenLiked string

If liked=true, whenLiked will contain the time when the member marked the film as liked. ISO 8601 format with UTC timezone, i.e. YYYY-MM-DDThh:mm:ssZ

favorited boolean

Will be true if the member listed the film as one of their four favorites.

inWatchlist boolean

Will be true if the film is in the member’s watchlist.

whenAddedToWatchlist string

If inWatchlist=true, whenAddedToWatchlist will contain the time when the member added the film to their watchlist. ISO 8601 format with UTC timezone, i.e. YYYY-MM-DDThh:mm:ssZ

whenCompletedInWatchlist string

If the member used to have the film in their watchlist, and subsequently watched the film, whenCompletedInWatchlist will contain the time when the member marked the film as watched. ISO 8601 format with UTC timezone, i.e. YYYY-MM-DDThh:mm:ssZ

rating number

The member’s rating for the film.

reviews
string[]

A list of LIDs for reviews the member has written for the film in the order they were added, with most recent reviews first.

diaryEntries
string[]

A list of LIDs for log entries the member has added for the film in diary order, with most recent entries first.

FilmRelationshipUpdateMessage

Properties

type enum ∈ {Error, Success}

The type of message.

code enum ∈ {InvalidRatingValue, UnableToRemoveWatch}

The error message code.

title string

The error message text in human-readable form.

FilmRelationshipUpdateRequest

When PATCHing a film relationship, you may send all of the current property values, or just those you wish to change. Properties that violate business rules (see watched below) or contain invalid values will be ignored.

Properties

watched boolean

Set to true to change the film’s status for the authenticated member to ‘watched’ or false for ‘not watched’. If the status is changed to ‘watched’ and the film is in the member’s watchlist, it will be removed as part of this action. You may not change the status of a film to ‘not watched’ if there is existing activity (a rating, review or diary entry) for the authenticated member—check the messages returned from this endpoint to ensure no such business rules have been violated.

liked boolean

Set to true to change the film’s status for the authenticated member to ‘liked’ or false for ‘not liked’.

inWatchlist boolean

Set to true to add the film to the authenticated member’s watchlist, or false to remove it.

rating number

Accepts values between 0.5 and 5.0, with increments of 0.5, or null (to remove the rating). If set, watched is assumed to be true.

FilmRelationshipUpdateResponse

Properties

data Required FilmRelationship

The response object.

messages Required

A list of messages the API client should show to the user.

FilmsAutocompleteResponse

Properties

items

The list of films.

FilmSearchItem < AbstractSearchItem

Inherited Properties

score Inherited number

A relevancy value that can be used to order results.

Properties

film FilmSummary

The film returned by the search.

FilmServicesResponse

Properties

items

The list of film services.

FilmsMemberRelationship

Properties

member MemberSummary

The member.

relationship FilmsRelationship

The relationship details.

FilmsMetadata

Properties

totalFilmCount integer

The total number of films.

filteredFilmCount integer

The number of films that match the filter for this request.

FilmsRelationship

Properties

counts FilmsRelationshipCounts

The number of watches and likes for the films.

FilmsRelationshipCounts

Properties

watches integer

The number of films the member has indicated they’ve seen (via the ‘eye’ icon) or has a log entry for.

likes integer

The number of films the member has indicated they liked.

FilmsResponse

Properties

next Cursor

The cursor to the next page of results.

items

The list of films.

FilmStatistics

Properties

film FilmIdentifier

The film for which statistics were requested.

counts FilmStatisticsCounts

The number of watches, ratings, likes, etc. for the film.

rating number

The weighted average rating of the film between 0.5 and 5.0. Will not be present if the film has not received sufficient ratings.

ratingsHistogram

A summary of the number of ratings at each increment between 0.5 and 5.0.

FilmStatisticsCounts

Properties

watches integer

The number of members who have watched the film.

likes integer

The number of members who have liked the film.

ratings