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. Parameters and endpoints marked as ‘First
Party’ are only available to Letterboxd’s own apps, due to licensing restrictions.
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
|
|
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
|
|
400 |
Bad request
|
|
401 |
There is no authenticated member, or the authenticated member does not own the resource
|
|
GET /auth/get-upload-url
Generate a single-use upload url for the current member, which can be used to upload a data file for the member.
Calls to this endpoint must include the access token for an authenticated member (see Authentication).
Response
200 |
Success
|
|
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
|
|
400 |
The credentials were not correct for the member, or the account was not found
|
|
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.
|
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
|
|
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 |
|
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.
|
similarTo |
query |
string
|
FIRST PARTY Specify the LID of a film to limit films to those similar to the specified film.
|
theme |
query |
string
|
FIRST PARTY Specify the code of a theme to limit films to those within the specified theme.
|
minigenre |
query |
string
|
FIRST PARTY Specify the code of a minigenre to limit films to those within the specified minigenre.
|
nanogenre |
query |
string
|
FIRST PARTY Specify the code of a nanogenre to limit films to those within the specified nanogenre.
|
includeGenre |
query |
|
Specify the LID of up to 100 genres to limit films to those within all of the specified genres.
|
excludeGenre |
query |
|
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 by 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, Rewatched, NotRewatched, Reviewed, NotReviewed, Owned, NotOwned, Customised, NotCustomised, Rated, NotRated, Liked, NotLiked, WatchedFromWatchlist, Watched, NotWatched, FeatureLength, NotFeatureLength, Fiction, Film, TV}
|
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
∈
{Billing, 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, AdditionalDirecting, Actor, Producer, ExecutiveProducer, Writer, OriginalWriter, Casting, Editor, Cinematography, AdditionalPhotography, ProductionDesign, ArtDirection, SetDecoration, SpecialEffects, VisualEffects, Stunts, Choreography, Composer, Songs, Sound, Costumes, MakeUp, Hairstyling, Studio}
|
The type of contribution.
|
Response
200 |
Success
|
|
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 |
|
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.
|
similarTo |
query |
string
|
FIRST PARTY Specify the LID of a film to limit films to those similar to the specified film.
|
theme |
query |
string
|
FIRST PARTY Specify the code of a theme to limit films to those within the specified theme.
|
minigenre |
query |
string
|
FIRST PARTY Specify the code of a minigenre to limit films to those within the specified minigenre.
|
nanogenre |
query |
string
|
FIRST PARTY Specify the code of a nanogenre to limit films to those within the specified nanogenre.
|
includeGenre |
query |
|
Specify the LID of up to 100 genres to limit films to those within all of the specified genres.
|
excludeGenre |
query |
|
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 by 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, Rewatched, NotRewatched, Reviewed, NotReviewed, Owned, NotOwned, Customised, NotCustomised, Rated, NotRated, Liked, NotLiked, WatchedFromWatchlist, Watched, NotWatched, FeatureLength, NotFeatureLength, Fiction, Film, TV}
|
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
|
|
404 |
No film collection matches the specified ID
|
|
GET /film/{id}
Get details about a film by ID. Supports an optional member ID to honor custom-poster settings.
Parameters
id Required |
path |
string
|
The LID of the film.
|
member |
query |
string
|
Specify the LID of a member to honor any custom-poster settings the member may have for the film, when viewed within the context of their profile or content.
|
Response
200 |
Success
|
|
404 |
No film matches the specified ID
|
|
GET /film/{id}/availability
FIRST PARTY Get availability data for a film by ID.
Parameters
id Required |
path |
string
|
The LID of the film.
|
Response
200 |
Success
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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.
|
member |
query |
string
|
Specify the LID of a member to return statistics for members followed by that member.
|
Response
200 |
Success
|
|
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 |
|
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.
|
similarTo |
query |
string
|
FIRST PARTY Specify the LID of a film to limit films to those similar to the specified film.
|
theme |
query |
string
|
FIRST PARTY Specify the code of a theme to limit films to those within the specified theme.
|
minigenre |
query |
string
|
FIRST PARTY Specify the code of a minigenre to limit films to those within the specified minigenre.
|
nanogenre |
query |
string
|
FIRST PARTY Specify the code of a nanogenre to limit films to those within the specified nanogenre.
|
includeGenre |
query |
|
Specify the LID of up to 100 genres to limit films to those within all of the specified genres.
|
excludeGenre |
query |
|
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 by 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, Rewatched, NotRewatched, Reviewed, NotReviewed, Owned, NotOwned, Customised, NotCustomised, Rated, NotRated, Liked, NotLiked, WatchedFromWatchlist, Watched, NotWatched, FeatureLength, NotFeatureLength, Fiction, Film, TV}
|
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, AuthenticatedMemberBasedOnLiked, AuthenticatedMemberRelatedToLiked, MemberRatingHighToLow, MemberRatingLowToHigh, AverageRatingHighToLow, AverageRatingLowToHigh, RatingHighToLow, RatingLowToHigh, FilmDurationShortestFirst, FilmDurationLongestFirst, BestMatch, 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 InWatchlist . The BestMatch sort order is only available when specifying one of the following: similarTo , theme , minigenre or nanogenre . 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* .
|
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 .
|
GET /films/countries
Get a list of countries supported by the /films endpoint.
Countries are returned in alphabetical order.
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.
GET /films/genres
Get a list of genres supported by the /films endpoint.
Genres are returned in alphabetical order.
GET /films/languages
Get a list of languages supported by the /films endpoint.
Languages are returned in alphabetical order.
POST /google-billing/subscription
Process an Google Purchase purchase token.
Response
200 |
Success
|
|
401 |
There is no authenticated member
|
|
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
|
|
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
|
|
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}/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 |
|
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.
|
similarTo |
query |
string
|
FIRST PARTY Specify the LID of a film to limit films to those similar to the specified film.
|
theme |
query |
string
|
FIRST PARTY Specify the code of a theme to limit films to those within the specified theme.
|
minigenre |
query |
string
|
FIRST PARTY Specify the code of a minigenre to limit films to those within the specified minigenre.
|
nanogenre |
query |
string
|
FIRST PARTY Specify the code of a nanogenre to limit films to those within the specified nanogenre.
|
includeGenre |
query |
|
Specify the LID of up to 100 genres to limit films to those within all of the specified genres.
|
excludeGenre |
query |
|
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 by 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, Rewatched, NotRewatched, Reviewed, NotReviewed, Owned, NotOwned, Customised, NotCustomised, Rated, NotRated, Liked, NotLiked, WatchedFromWatchlist, Watched, NotWatched, FeatureLength, NotFeatureLength, Fiction, Film, TV}
|
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, WhenAddedToListEarliestFirst, Shuffle, FilmName, OwnerRatingHighToLow, OwnerRatingLowToHigh, AuthenticatedMemberRatingHighToLow, AuthenticatedMemberRatingLowToHigh, AuthenticatedMemberBasedOnLiked, AuthenticatedMemberRelatedToLiked, 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
|
|
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
|
|
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
|
|
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
|
|
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), WhenLiked, WhenPublishedLatestFirst, WhenPublishedEarliestFirst, WhenCreatedLatestFirst, WhenCreatedEarliestFirst, WhenAccessedLatestFirst, WhenAccessedEarliestFirst, 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 the film.
|
clonedFrom |
query |
string
|
Specify the LID of a list to return lists that were cloned from the 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, Accessed}
|
Must be used in conjunction with member . Defaults to Owner , which returns lists owned by the member. Use Liked to return lists liked by the member or Accessed to return shared lists that have been viewed 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, NotPublishedOrShared, SharedAnyone, SharedFriends, Owned}
|
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 private 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}
|
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 |
|
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 in the list.
|
Response
200 |
Success
|
|
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
|
|
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
|
|
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).
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=HasDiaryDate If 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 |
|
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 |
|
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 by 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, Rewatched, NotRewatched, Reviewed, NotReviewed, Owned, NotOwned, Customised, NotCustomised, Liked, NotLiked, Fiction, Film, TV}
|
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}
|
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
|
|
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
|
|
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
|
|
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
|
|
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}/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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
400 |
Bad request
|
|
401 |
There is no authenticated member
|
|
GET /me/check-tag
Check whether a tag is being merged before update.
Response
200 |
Success
|
|
204 |
successful operation
|
|
400 |
Bad request
|
|
401 |
There is no authenticated member
|
|
403 |
The signed-in user does not have permission to mass-edit tags.
|
|
DELETE /me/delete-tag
Delete a tag.
Calls to this endpoint must include the access token for an authenticated member (see Authentication). Tags can only be deleted by their owner.
Response
204 |
Success
|
|
400 |
Bad request
|
|
401 |
There is no authenticated member
|
|
403 |
The signed-in user does not have permission to mass-edit tags.
|
|
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
|
|
PATCH /me/update-tag
Update the tag code of a tagging.
Calls to this endpoint must include the access token for an authenticated member (see Authentication). Tags may only be edited by their owner.
Response
200 |
Success
|
|
401 |
There is no authenticated member
|
|
403 |
The signed-in user does not have permission to mass-edit tags.
|
|
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
|
|
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}
|
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}
|
Only supported for paying members.DEPRECATED Use include instead.
|
where |
query |
enum[]
∈
{OwnActivity, NotOwnActivity, IncomingActivity, NotIncomingActivity, NetworkActivity}
|
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
|
|
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
|
|
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
|
|
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
|
|
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}/statistics
Get statistical data about a member by ID.
Parameters
id Required |
path |
string
|
The LID of the member.
|
Response
200 |
Success
|
|
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 |
|
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.
|
similarTo |
query |
string
|
FIRST PARTY Specify the LID of a film to limit films to those similar to the specified film.
|
theme |
query |
string
|
FIRST PARTY Specify the code of a theme to limit films to those within the specified theme.
|
minigenre |
query |
string
|
FIRST PARTY Specify the code of a minigenre to limit films to those within the specified minigenre.
|
nanogenre |
query |
string
|
FIRST PARTY Specify the code of a nanogenre to limit films to those within the specified nanogenre.
|
includeGenre |
query |
|
Specify the LID of up to 100 genres to limit films to those within all of the specified genres.
|
excludeGenre |
query |
|
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 by 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, Rewatched, NotRewatched, Reviewed, NotReviewed, Owned, NotOwned, Customised, NotCustomised, Rated, NotRated, Liked, NotLiked, WatchedFromWatchlist, Watched, NotWatched, FeatureLength, NotFeatureLength, Fiction, Film, TV}
|
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
|
|
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 the 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 the 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 InWatchlist .
|
list |
query |
string
|
Specify the LID of a list to return members who like the list.
|
listRelationship |
query |
enum
∈
{Owner, Liked (default), Accessed}
|
Must be used in conjunction with list . Defaults to Liked , which returns the list of members who have liked the list . Use Accessed to return the list of members who have viewed the shared list . The authenticated member must be the owner of the list in order to use Accessed .
|
review |
query |
string
|
Specify the LID of a review to return members who like the review.
|
GET /members/pronouns
Get a list of pronouns supported by the PATCH
/me endpoint.
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.
Response
201 |
Success
|
|
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 ).
|
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, NamesAndKeywords}
|
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, StorySearchItem, ArticleSearchItem, PodcastSearchItem}
|
The types of results to search for. Default to all SearchResultTypes.
|
contributionType |
query |
enum
∈
{Director, CoDirector, AdditionalDirecting, Actor, Producer, ExecutiveProducer, Writer, OriginalWriter, Casting, Editor, Cinematography, AdditionalPhotography, ProductionDesign, ArtDirection, SetDecoration, SpecialEffects, VisualEffects, Stunts, Choreography, Composer, Songs, Sound, Costumes, MakeUp, Hairstyling, 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 .
|
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 from that member’s account.
|
where |
query |
enum[]
∈
{Published, NotPublished}
|
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
|
|
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
|
|
404 |
No story matches the specified ID
|
|