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.
Authorization
The Letterboxd API uses standard OAuth 2
Resource Owner, Client Credentials, Authorization Code and Refresh Token authorization
flows to grant access via an access token. Resource Owner tokens are for first-party use only, and may be refreshed at regular
intervals to keep the member signed in. Third-party API consumers must use the Client Credentials or Authorization Code flows
instead of the Resource Owner grant (Client Credentials returns publicly available data, while Authorization Code is
required for any operation that requires member authorization, such as accessing private data or modifying a member’s data).
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:
Resource Owner FIRST PARTY LEGACY
| grant_type Required |
string |
Use value: password |
| username Required |
string |
The member’s username or email address. |
| password Required |
string |
The member’s password. |
| scope |
string |
Not required for first-party API clients. Legacy API consumers may use this parameter to request additional scopes, over and above the default scopes. See Scopes for more details. |
| client_id Required |
string |
Your API key. |
| client_secret Required |
string |
Your API secret. |
Client Credentials
| grant_type Required |
string |
Use value: client_credentials |
| client_id Required |
string |
Your API key. |
| client_secret Required |
string |
Your API secret. |
Authorization Code
| grant_type Required |
string |
Use value: authorization_code |
| code Required |
string |
The authorization code returned from the grant flow. |
| redirect_uri Required |
string |
The URI used when initiating the authorization-code flow. |
| client_id Required |
string |
Your API key. |
| client_secret Required |
string |
Your API secret. |
Refresh a token
| grant_type Required |
string |
Use value: refresh_token |
| refresh_token Required |
string |
The member’s current refresh-token value. |
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 repeat the relevant auth flow to generate a new token.
Scopes
A scope is a security requirement that must be met before you can use an endpoint. Scopes are tied to an access token. Letterboxd offers the scopes detailed here.
Some scopes are automatically granted based on the auth flow in use, and you do not need to request authorisation from the member for these defaults. If you need to request additional scopes beyond the defaults, these will be shown to the person using your app, and granted if they agree to the scopes being sought.
When requesting multiple scopes, they must be provided in the form of a space- or plus-delimited string. For example profile:modify content:modify or profile:modify+content:modify.
Authorization Code Flow
Obtaining an authorization code follows a standard OAuth2 code flow. To use this flow, you must apply for and receive an API key.
With the correct credentials, make a GET or POST request to the /authorize endpoint, using the following query or form params:
| response_type Required |
string |
Use value: code |
| client_id Required |
string |
Your API key. |
| redirect_uri Required |
string |
The URI to which the code will be sent. This must exactly match the URI that is registered with your API credentials. |
| scope |
string |
The scopes you wish to authorize for the access token. These scopes will be presented to the authorizing member for approval. See Scopes for more details. |
| state Recommended |
string |
Useful for preventing CSRF attacks. If you include this value, it will be returned along with the authorization code. |
A valid request will return a page on which the currently signed-in member can approve the requested scopes. If there is no signed-in member, a sign-in page is returned. If the member approves access to the scopes, the request is redirected to the provided URI with the authorization code as a path parameter (and the state value, if provided).
Once you have an authorization code, you may redeem it for an access token.
OpenID Connect
Letterboxd supports OpenID Connect (OIDC). To use OIDC, you must request the required scopes.
Discovery information is available at Letterboxd’s openid-configuration endpoint.
Endpoints
POST /apple-iap/subscription
Process an Apple In-app Purchase receipt.
Response
| 200 |
Success
|
|
| 401 |
There is no authenticated member
|
|
GET /auth/authorize
Initiate the authorize-code-grant flow.
See the Authorization Code Flow for more details.
Response
| 200 |
The scope-approval page.
|
|
| 400 |
Something was wrong with your code-grant form.
|
|
POST /auth/authorize
Initiate the authorize-code-grant flow.
See Authorization Code Flow for more details.
Response
| 200 |
The scope-approval page.
|
|
| 400 |
Something was wrong with your code-grant form.
|
|
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. Check the member’s spam/junk 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.
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.
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
Apply for an authorization token using one of the supported authorization flows.
Use this endpoint to generate or refresh an auth token. See Authorization 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.
|
| availabilityType |
query |
|
Specify the availability types to limit films to those with those availability types. The list of availability types can be found by using the /films/availability-types endpoint.
|
| exclusive |
query |
boolean
|
Set to true to limit films to those available on only one service.
|
| unavailable |
query |
boolean
|
Set to true to limit films to those not available on any services.
|
| includeOwned |
query |
boolean
|
Set to true to include films that the user owns.
|
| negate |
query |
boolean
|
Set to true to invert the current service filtering options.
|
| 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.
|
| availabilityType |
query |
|
Specify the availability types to limit films to those with those availability types. The list of availability types can be found by using the /films/availability-types endpoint.
|
| exclusive |
query |
boolean
|
Set to true to limit films to those available on only one service.
|
| unavailable |
query |
boolean
|
Set to true to limit films to those not available on any services.
|
| includeOwned |
query |
boolean
|
Set to true to include films that the user owns.
|
| negate |
query |
boolean
|
Set to true to invert the current service filtering options.
|
| 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.
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.
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.
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.
|
| availabilityType |
query |
|
Specify the availability types to limit films to those with those availability types. The list of availability types can be found by using the /films/availability-types endpoint.
|
| exclusive |
query |
boolean
|
Set to true to limit films to those available on only one service.
|
| unavailable |
query |
boolean
|
Set to true to limit films to those not available on any services.
|
| includeOwned |
query |
boolean
|
Set to true to include films that the user owns.
|
| negate |
query |
boolean
|
Set to true to invert the current service filtering options.
|
| 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/availability-types
Get a list of availability types supported by the /films endpoint.
Availability types are returned in alphabetical order.
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.
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.
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.
|
| availabilityType |
query |
|
Specify the availability types to limit films to those with those availability types. The list of availability types can be found by using the /films/availability-types endpoint.
|
| exclusive |
query |
boolean
|
Set to true to limit films to those available on only one service.
|
| unavailable |
query |
boolean
|
Set to true to limit films to those not available on any services.
|
| includeOwned |
query |
boolean
|
Set to true to include films that the user owns.
|
| negate |
query |
boolean
|
Set to true to invert the current service filtering options.
|
| 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, OwnerDiaryLatestFirst, OwnerDiaryEarliestFirst, AuthenticatedMemberRatingHighToLow, AuthenticatedMemberRatingLowToHigh, AuthenticatedMemberDiaryLatestFirst, AuthenticatedMemberDiaryEarliestFirst, AuthenticatedMemberBasedOnLiked, AuthenticatedMemberRelatedToLiked, MemberRatingHighToLow, MemberRatingLowToHigh, MemberDiaryLatestFirst, MemberDiaryEarliestFirst, 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.
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.
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.
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.
Response
| 200 |
Success
|
|
| 400 |
Bad request
|
|
| 401 |
There is no authenticated member
|
|
POST /lists
Create a list.
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=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 |
|
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.
|
| availabilityType |
query |
|
Specify the availability types to limit films to those with those availability types. The list of availability types can be found by using the /films/availability-types endpoint.
|
| exclusive |
query |
boolean
|
Set to true to limit films to those available on only one service.
|
| unavailable |
query |
boolean
|
Set to true to limit films to those not available on any services.
|
| includeOwned |
query |
boolean
|
Set to true to include films that the user owns.
|
| negate |
query |
boolean
|
Set to true to invert the current service filtering options.
|
| 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.
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.
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.
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.
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.
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.
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.
Response
| 200 |
Success
|
|
| 401 |
There is no authenticated member
|
|
PATCH /me
Update the profile settings for the authenticated member.
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.
|
|
POST /me/collect-item
Collect a hunt item.
Response
| 200 |
Success
|
|
| 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.
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.
Response
| 204 |
Success
|
|
| 401 |
There is no authenticated member
|
|
POST /me/disable
Deactivate account.
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.
Response
| 204 |
Success
|
|
| 401 |
There is no authenticated member
|
|
PATCH /me/update-tag
Update the tag code of a tagging.
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.
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, ReviewResponseActivity, 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, ReviewResponseActivity, 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.
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.
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.
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.
|
| availabilityType |
query |
|
Specify the availability types to limit films to those with those availability types. The list of availability types can be found by using the /films/availability-types endpoint.
|
| exclusive |
query |
boolean
|
Set to true to limit films to those available on only one service.
|
| unavailable |
query |
boolean
|
Set to true to limit films to those not available on any services.
|
| includeOwned |
query |
boolean
|
Set to true to include films that the user owns.
|
| negate |
query |
boolean
|
Set to true to invert the current service filtering options.
|
| 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
|
|
GET /userinfo
Response
| default |
successful operation
|
|
