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).

Example implementations

These implementations from Letterboxd engineers (Ruby) and third parties may assist you:

Endpoints

POST /apple-iap/subscription

Process an Apple In-app Purchase receipt.

Request

AppleIAPSubscriptionRequest

Response

200	Success	AppleIAPSubscriptionResponse
401	There is no authenticated member

POST /auth/forgotten-password-request

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

Request

ForgottenPasswordRequest

Response

204	Success (the email was dispatched if it matched an existing account)
400	Bad request
429	Too many forgotten password requests have been received for this email address. The email is probably in the member’s spam folder

GET /auth/get-login-token

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

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

Response

200	Success	LoginTokenResponse
400	Bad request
401	There is no authenticated member, or the authenticated member does not own the resource

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	UploadUrlResponse
400	Bad request
401	There is no authenticated member, or the authenticated member does not own the resource

POST /auth/revoke

Response

default

successful operation

POST /auth/token

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

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

Response

200	Success	AccessToken
400	The credentials were not correct for the member, or the account was not found	OAuthError

GET /auth/username-check

Check if a username is available to register.

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

Parameters

username Required

query

string

The username to check.

Response

200

Success

UsernameCheckResponse

DELETE /comment/{id}

Delete a comment.

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

Parameters

id Required

path

string

The LID of the comment/reply.

Response

204	Success
400	Bad request
401	There is no authenticated member, or the authenticated member does not own the resource
403	The window for deleting this comment has expired
404	No comment matches the specified ID

PATCH /comment/{id}

Update the message portion of a comment.

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

Request

CommentUpdateRequest

Parameters

id Required

path

string

The LID of the comment/reply.

Response

200	Completed, possibly with messages	CommentUpdateResponse
401	There is no authenticated member, or the authenticated member does not own the resource
404	No comment matches the specified ID

POST /comment/{id}/report

Report a comment by ID.

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

Request

ReportCommentRequest

Parameters

id Required

path

string

The LID of the comment/reply.

Response

204	Success
401	There is no authenticated member
404	No comment matches the specified ID

GET /contributor/{id}

Get details about a film contributor by ID.

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

Parameters

id Required

path

string

The LID of the contributor.

Response

200	Success	Contributor
404	No contributor matches the specified ID

GET /contributor/{id}/contributions

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

Use the ‘next’ cursor to move through the list

Parameters

id Required	path	string	The LID of the contributor.
cursor	query	string	The pagination cursor.
perPage	query	integer	The number of items to include per page (default is `20`, maximum is `100`).
filmId	query	string[] multiple parameters (`filmId=aaa&filmId=bbb`)	Specify up to 100 Letterboxd IDs or TMDB IDs prefixed with `tmdb:`, or IMDB IDs prefixed with `imdb:`
genre	query	string	Specify the LID of a genre to limit films to those within the specified genre.
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	string[] multiple parameters (`includeGenre=aaa&includeGenre=bbb`)	Specify the LID of up to 100 genres to limit films to those within all of the specified genres.
excludeGenre	query	string[] multiple parameters (`excludeGenre=aaa&excludeGenre=bbb`)	Specify the LID of up to 100 genres to limit films to those within none of the specified genres.
country	query	string	Specify the ISO 3166-1 defined code of the country to limit films to those produced 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} multiple parameters (`where=aaa&where=bbb`)	Specify one or more values to limit the list of films accordingly.
member	query	string	Specify the LID of a member to limit the returned films according to the value set in `memberRelationship` or to access the `MemberRating*` sort options.
memberRelationship	query	enum ∈ {Ignore, Watched (default), NotWatched, Liked, NotLiked, Rated, NotRated, InWatchlist, NotInWatchlist, Favorited}	Must be used in conjunction with `member`. Defaults to `Watched`. Specify the type of relationship to limit the returned films accordingly. Use `Ignore` if you only intend to specify the member for use with `sort=MemberRating*`.
includeFriends	query	enum ∈ {None (default), All, Only}	Must be used in conjunction with `member`. Defaults to `None`, which only returns films from the member’s account. Use `Only` to return films from the member’s friends, and `All` to return films from both the member and their friends.
tag	query	string	DEPRECATED Use `tagCode` instead.
tagCode	query	string	Specify a tag code to limit the returned films to those tagged accordingly.
tagger	query	string	Must be used with `tagCode`. Specify the LID of a member to focus the tag filter on the member.
includeTaggerFriends	query	enum ∈ {None (default), All, Only}	Must be used in conjunction with `tagger`. Defaults to `None`, which filters tags set by the member. Use `Only` to filter tags set by the member’s friends, and `All` to filter tags set by both the member and their friends.
sort	query	enum ∈ {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	FilmContributionsResponse
404	No contributor matches the specified ID

GET /film-collection/{id}

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

Parameters

id Required	path	string	The LID of the film collection.
filmId	query	string[] multiple parameters (`filmId=aaa&filmId=bbb`)	Specify up to 100 Letterboxd IDs or TMDB IDs prefixed with `tmdb:`, or IMDB IDs prefixed with `imdb:`
genre	query	string	Specify the LID of a genre to limit films to those within the specified genre.
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	string[] multiple parameters (`includeGenre=aaa&includeGenre=bbb`)	Specify the LID of up to 100 genres to limit films to those within all of the specified genres.
excludeGenre	query	string[] multiple parameters (`excludeGenre=aaa&excludeGenre=bbb`)	Specify the LID of up to 100 genres to limit films to those within none of the specified genres.
country	query	string	Specify the ISO 3166-1 defined code of the country to limit films to those produced 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} multiple parameters (`where=aaa&where=bbb`)	Specify one or more values to limit the list of films accordingly.
member	query	string	Specify the LID of a member to limit the returned films according to the value set in `memberRelationship` or to access the `MemberRating*` sort options.
memberRelationship	query	enum ∈ {Ignore, Watched (default), NotWatched, Liked, NotLiked, Rated, NotRated, InWatchlist, NotInWatchlist, Favorited}	Must be used in conjunction with `member`. Defaults to `Watched`. Specify the type of relationship to limit the returned films accordingly. Use `Ignore` if you only intend to specify the member for use with `sort=MemberRating*`.
includeFriends	query	enum ∈ {None (default), All, Only}	Must be used in conjunction with `member`. Defaults to `None`, which only returns films from the member’s account. Use `Only` to return films from the member’s friends, and `All` to return films from both the member and their friends.
tag	query	string	DEPRECATED Use `tagCode` instead.
tagCode	query	string	Specify a tag code to limit the returned films to those tagged accordingly.
tagger	query	string	Must be used with `tagCode`. Specify the LID of a member to focus the tag filter on the member.
includeTaggerFriends	query	enum ∈ {None (default), All, Only}	Must be used in conjunction with `tagger`. Defaults to `None`, which filters tags set by the member. Use `Only` to filter tags set by the member’s friends, and `All` to filter tags set by both the member and their friends.
sort	query	enum ∈ {FilmName, ReleaseDateLatestFirst, ReleaseDateEarliestFirst, AuthenticatedMemberRatingHighToLow, AuthenticatedMemberRatingLowToHigh, MemberRatingHighToLow, MemberRatingLowToHigh, AverageRatingHighToLow, AverageRatingLowToHigh, FilmDurationShortestFirst, FilmDurationLongestFirst, FilmPopularity (default), FilmPopularityThisWeek, FilmPopularityThisMonth, FilmPopularityThisYear, FilmPopularityWithFriends, FilmPopularityWithFriendsThisWeek, FilmPopularityWithFriendsThisMonth, FilmPopularityWithFriendsThisYear}	The order in which the films should be returned. Defaults to `FilmPopularity`, which is an all-time measurement of the amount of activity the film has received. The `WithFriends` values are only available to signed-in members and consider popularity amongst the signed-in member’s friends.The `AuthenticatedMember` values are only available to signed-in members.The `MemberRating` values must be used in conjunction with `member` and are only available when specifying a single member (i.e. `IncludeFriends=None`).

Response

200	Success	FilmCollection
404	No film collection matches the specified ID

GET /film/{id}

Get details about a film by ID. 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	Film
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	FilmAvailabilityResponse
404	No film matches the specified ID

GET /film/{id}/friends

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

Parameters

id Required

path

string

The LID of the film.

Response

200	Success	FilmRelationship
401	There is no authenticated member
404	No film matches the specified ID

GET /film/{id}/me

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

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

Parameters

id Required

path

string

The LID of the film.

Response

200	Success	FilmRelationship
401	There is no authenticated member
404	No film matches the specified ID

PATCH /film/{id}/me

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

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

Request

FilmRelationshipUpdateRequest

Parameters

id Required

path

string

The LID of the film.

Response

200	Success	FilmRelationshipUpdateResponse
401	There is no authenticated member
404	No film matches the specified ID

GET /film/{id}/members

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

Parameters

id Required	path	string	The LID of the film.
cursor	query	string	The pagination cursor.
perPage	query	integer	The number of items to include per page (default is `20`, maximum is `100`).
sort	query	enum ∈ {Date (default), Name, MemberPopularity, MemberPopularityThisWeek, MemberPopularityThisMonth, MemberPopularityThisYear, MemberPopularityWithFriends, MemberPopularityWithFriendsThisWeek, MemberPopularityWithFriendsThisMonth, MemberPopularityWithFriendsThisYear}	Defaults to `Date`, which has different semantics based on the request:When `review` is specified, members who most recently liked the review appear first.When `list` is specified, members who most recently liked the list appear first.When `film` is specified and `filmRelationship=Watched`, members who most recently watched the film appear first.When `film` is specified and `filmRelationship=Liked`, members who most recently liked the film appear first.When `film` is specified and `filmRelationship=InWatchlist`, members who most recently added the film to their watchlist appear first.When `member` is specified and `memberRelationship=IsFollowing`, most recently followed members appear first.When `member` is specified and `memberRelationship=IsFollowedBy`, most recent followers appear first.Otherwise, members who most recently joined the site appear first.The `*WithFriends` values are only available to authenticated members and consider popularity amongst the member’s friends.
member	query	string	Specify the LID of a member to return members who follow or are followed by that member.
memberRelationship	query	enum ∈ {IsFollowing (default), IsFollowedBy}	Must be used in conjunction with `member`. Defaults to `IsFollowing`, which returns the list of members followed by the `member`. Use `IsFollowedBy` to return the list of members that follow the `member`.
filmRelationship	query	enum ∈ {Ignore, Watched (default), NotWatched, Liked, NotLiked, Rated, NotRated, InWatchlist, NotInWatchlist, Favorited}	Must be used in conjunction with `film`. Defaults to `Watched`, which returns the list of members who have seen the `film`. Specify the type of relationship to limit the returned members accordingly.

Response

200	Success	MemberFilmRelationshipsResponse
404	No film matches the specified ID

POST /film/{id}/report

Report a film by ID.

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

Request

ReportFilmRequest

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	FilmStatistics
404	No film matches the specified ID

GET /films

A cursored window over the list of films.

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

Parameters

cursor	query	string	The pagination cursor.
perPage	query	integer	The number of items to include per page (default is `20`, maximum is `100`).
filmId	query	string[] multiple parameters (`filmId=aaa&filmId=bbb`)	Specify up to 100 Letterboxd IDs or TMDB IDs prefixed with `tmdb:`, or IMDB IDs prefixed with `imdb:`
genre	query	string	Specify the LID of a genre to limit films to those within the specified genre.
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	string[] multiple parameters (`includeGenre=aaa&includeGenre=bbb`)	Specify the LID of up to 100 genres to limit films to those within all of the specified genres.
excludeGenre	query	string[] multiple parameters (`excludeGenre=aaa&excludeGenre=bbb`)	Specify the LID of up to 100 genres to limit films to those within none of the specified genres.
country	query	string	Specify the ISO 3166-1 defined code of the country to limit films to those produced 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} multiple parameters (`where=aaa&where=bbb`)	Specify one or more values to limit the list of films accordingly.
member	query	string	Specify the LID of a member to limit the returned films according to the value set in `memberRelationship` or to access the `MemberRating*` sort options.
memberRelationship	query	enum ∈ {Ignore, Watched (default), NotWatched, Liked, NotLiked, Rated, NotRated, InWatchlist, NotInWatchlist, Favorited}	Must be used in conjunction with `member`. Defaults to `Watched`. Specify the type of relationship to limit the returned films accordingly. Use `Ignore` if you only intend to specify the member for use with `sort=MemberRating*`.
includeFriends	query	enum ∈ {None (default), All, Only}	Must be used in conjunction with `member`. Defaults to `None`, which only returns films from the member’s account. Use `Only` to return films from the member’s friends, and `All` to return films from both the member and their friends.
tag	query	string	DEPRECATED Use `tagCode` instead.
tagCode	query	string	Specify a tag code to limit the returned films to those tagged accordingly.
tagger	query	string	Must be used with `tagCode`. Specify the LID of a member to focus the tag filter on the member.
includeTaggerFriends	query	enum ∈ {None (default), All, Only}	Must be used in conjunction with `tagger`. Defaults to `None`, which filters tags set by the member. Use `Only` to filter tags set by the member’s friends, and `All` to filter tags set by both the member and their friends.
sort	query	enum ∈ {FilmName, DateLatestFirst, DateEarliestFirst, ReleaseDateLatestFirst, ReleaseDateEarliestFirst, AuthenticatedMemberRatingHighToLow, AuthenticatedMemberRatingLowToHigh, 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`.

Response

200

Success

FilmsResponse

GET /films/autocomplete

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

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

Parameters

perPage	query	integer	The number of items to include per page (default is `20`, maximum is `100`).
input Required	query	string	The word, partial word or phrase to match against.
adult	query	boolean	Whether to include adult content in search results. Default to `false`.

GoogleBillingSubscriptionRequest

Response

200	Success	GoogleBillingSubscriptionResponse
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	List
404	No list matches the specified ID

PATCH /list/{id}

Update a list by ID.

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

Request

ListUpdateRequest

Parameters

id Required

path

string

The LID of the list.

Response

200	Success	ListUpdateResponse
400	Bad request
401	There is no authenticated member, or the authenticated member does not own the resource
404	No list matches the specified ID

GET /list/{id}/comments

A cursored window over the comments for a list.

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

Parameters

id Required	path	string	The LID of the list.
cursor	query	string	The pagination cursor.
perPage	query	integer	The number of items to include per page (default is `20`, maximum is `100`).
sort	query	enum ∈ {Date, DateLatestFirst, Updates}	Defaults to `Date`. The `Updates` sort order returns newest content first. Use this to get the most recently posted or edited comments, and pass `includeDeletions=true` to remain consistent in the case where a comment has been deleted.
includeDeletions	query	boolean	Use this to discover any comments that were deleted.

Response

200	Success	ListCommentsResponse
404	No list matches the specified ID

POST /list/{id}/comments

Create a comment on a list.

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

Request

CommentCreationRequest

Parameters

id Required

path

string

The LID of the list.

Response

201	Success	ListComment
204	A comment with the same message already exists (no action was taken)
400	Bad request
401	There is no authenticated member
403	The authenticated member is not authorized to comment on this list
404	No list matches the specified ID

GET /list/{id}/entries

Get entries for a list by ID.

Parameters

id Required	path	string	The LID of the list.
cursor	query	string	The pagination cursor.
perPage	query	integer	The number of items to include per page (default is `20`, maximum is `100`).
filmId	query	string[] multiple parameters (`filmId=aaa&filmId=bbb`)	Specify up to 100 Letterboxd IDs or TMDB IDs prefixed with `tmdb:`, or IMDB IDs prefixed with `imdb:`
genre	query	string	Specify the LID of a genre to limit films to those within the specified genre.
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	string[] multiple parameters (`includeGenre=aaa&includeGenre=bbb`)	Specify the LID of up to 100 genres to limit films to those within all of the specified genres.
excludeGenre	query	string[] multiple parameters (`excludeGenre=aaa&excludeGenre=bbb`)	Specify the LID of up to 100 genres to limit films to those within none of the specified genres.
country	query	string	Specify the ISO 3166-1 defined code of the country to limit films to those produced 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} multiple parameters (`where=aaa&where=bbb`)	Specify one or more values to limit the list of films accordingly.
member	query	string	Specify the LID of a member to limit the returned films according to the value set in `memberRelationship` or to access the `MemberRating*` sort options.
memberRelationship	query	enum ∈ {Ignore, Watched (default), NotWatched, Liked, NotLiked, Rated, NotRated, InWatchlist, NotInWatchlist, Favorited}	Must be used in conjunction with `member`. Defaults to `Watched`. Specify the type of relationship to limit the returned films accordingly. Use `Ignore` if you only intend to specify the member for use with `sort=MemberRating*`.
includeFriends	query	enum ∈ {None (default), All, Only}	Must be used in conjunction with `member`. Defaults to `None`, which only returns films from the member’s account. Use `Only` to return films from the member’s friends, and `All` to return films from both the member and their friends.
tag	query	string	DEPRECATED Use `tagCode` instead.
tagCode	query	string	Specify a tag code to limit the returned films to those tagged accordingly.
tagger	query	string	Must be used with `tagCode`. Specify the LID of a member to focus the tag filter on the member.
includeTaggerFriends	query	enum ∈ {None (default), All, Only}	Must be used in conjunction with `tagger`. Defaults to `None`, which filters tags set by the member. Use `Only` to filter tags set by the member’s friends, and `All` to filter tags set by both the member and their friends.
sort	query	enum ∈ {ListRanking (default), WhenAddedToList, 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	ListEntriesResponse
404	No list matches the specified ID

GET /list/{id}/me

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

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

Parameters

id Required

path

string

The LID of the list.

Response

200	Success	ListRelationship
401	There is no authenticated member
404	No list matches the specified ID

PATCH /list/{id}/me

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

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

Request

ListRelationshipUpdateRequest

Parameters

id Required

path

string

The LID of the list.

Response

200	Success	ListRelationshipUpdateResponse
401	There is no authenticated member, or the authenticated member does not own the resource
404	No list matches the specified ID

POST /list/{id}/report

Report a list by ID.

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

Request

ReportListRequest

Parameters

id Required

path

string

The LID of the list.

Response

204	Success
401	There is no authenticated member
404	No list matches the specified ID

GET /list/{id}/statistics

Get statistical data about a list by ID.

Parameters

id Required

path

string

The LID of the list.

Response

200	Success	ListStatistics
404	No list matches the specified ID

GET /lists

A cursored window over a list of lists.

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

Parameters

cursor	query	string	The pagination cursor.
perPage	query	integer	The number of items to include per page (default is `20`, maximum is `100`).
sort	query	enum ∈ {Date (default), 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} multiple parameters (`where=aaa&where=bbb`)	Specify `Clean` to return lists that do not contain profane language. Specify `Published` to return the member’s lists that have been made public. Note that 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} multiple parameters (`filter=aaa&filter=bbb`)	Specify `NoDuplicateMembers` to limit the list to only the first list for each member. `NoDuplicateMembers` is only available when using these sort orders: `Date`, `WhenPublishedLatestFirst`, `WhenCreatedLatestFirst`.
filmsOfNote	query	string[] multiple parameters (`filmsOfNote=aaa&filmsOfNote=bbb`)	Specify the LIDs of any film(s) you wish to see the status for in respect of the returned list(s). For each nominated film, the response will indicate (for each returned list) whether the list contains the film, and if so, its rank/position in the list.

Response

200	Success	ListsResponse
400	Bad request
403	There is no authenticated member, or the authenticated member does not own the resource (when requesting `where=NotPublished`)
404	No film, member, tag or list matches the specified ID.

PATCH /lists

Add one or more films to one or more lists.

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

Request

ListAdditionRequest

Response

200	Success	ListAdditionResponse
400	Bad request
401	There is no authenticated member

POST /lists

Create a list.

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

Request

ListCreationRequest

Response

200	Success	ListCreateResponse
400	Bad request
401	There is no authenticated member

GET /lists/topics

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

Response

200

Success

TopicsResponse

GET /log-entries

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

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

Parameters

cursor	query	string	The pagination cursor.
perPage	query	integer	The number of items to include per page (default is `20`, maximum is `100`).
sort	query	enum ∈ {WhenAdded (default), Date, DiaryCount, ReviewCount, WhenLiked, EntryRatingHighToLow, EntryRatingLowToHigh, RatingHighToLow, RatingLowToHigh, AuthenticatedMemberRatingHighToLow, AuthenticatedMemberRatingLowToHigh, MemberRatingHighToLow, MemberRatingLowToHigh, AverageRatingHighToLow, AverageRatingLowToHigh, ReleaseDateLatestFirst, ReleaseDateEarliestFirst, FilmName, FilmDurationShortestFirst, FilmDurationLongestFirst, ReviewPopularity, ReviewPopularityThisWeek, ReviewPopularityThisMonth, ReviewPopularityThisYear, ReviewPopularityWithFriends, ReviewPopularityWithFriendsThisWeek, ReviewPopularityWithFriendsThisMonth, ReviewPopularityWithFriendsThisYear, FilmPopularity, FilmPopularityThisWeek, FilmPopularityThisMonth, FilmPopularityThisYear, FilmPopularityWithFriends, FilmPopularityWithFriendsThisWeek, FilmPopularityWithFriendsThisMonth, FilmPopularityWithFriendsThisYear}	The order in which the log entries should be returned. Defaults to `WhenAdded`, which orders by creation date, unless you specify `where=HasDiaryDate` in which case the default is `Date`.The `AuthenticatedMember` values are only available to signed-in members.The `MemberRating` values must be used in conjunction with `member` and are only available when specifying a single member (i.e. `IncludeFriends=None`).The `ReviewPopularity` values return reviews with more activity (likes/comments) first, and imply `where=HasReview`.The `FilmPopularity` values return reviews for films with more combined activity first.The `WithFriends` values are only available to signed-in members and consider popularity amongst the signed-in member’s friends.The `Date` value sorts by the diary date, and implies `where=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	string[] multiple parameters (`includeGenre=aaa&includeGenre=bbb`)	Specify the LID of up to 100 genres to limit the returned log entries to those for films within all of the specified genres.
excludeGenre	query	string[] multiple parameters (`excludeGenre=aaa&excludeGenre=bbb`)	Specify the LID of up to 100 genres to limit the returned log entries to those for films within none of the specified genres.
country	query	string	Specify the ISO 3166-1 defined code of the country to limit films to those produced 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} multiple parameters (`where=aaa&where=bbb`)	Specify one or more values to limit the returned log entries accordingly. `Released`, `NotReleased`, `FeatureLength` and `NotFeatureLength` refer to properties of the associated film rather than to the relevant log entry. Use `InWatchlist` or `NotInWatchlist` to limit the returned log entries based on the contents of the authenticated member’s watchlist. Use `Watched` and `NotWatched` to limit the returned log entries based on the authenticated member’s list of watched films. (Note: you can specify `member` and `filmMemberRelationship` to further limit returned entries based on another member’s films or watchlist.) Use `HasDiaryDate` to limit the returned log entries to those that appear in a member’s diary. Use `HasReview` to limit the returned log entries to those containing a review. Use `Clean` to exclude reviews that contain profane language. Use `NoSpoilers` to exclude reviews where the owner has indicated that the review text contains plot spoilers for the film. Use `Rated` to limit the returned log entries to those that have a rating (use `minRating` and `maxRating` for more control). Use `NotRated` to limit the returned log entries to those that do not have a rating. Use `Fiction` to exclude log entries of documentaries. Use `Film` to exclude log entries of tv shows. Use `TV` to only return log entries of tv shows.
filter	query	enum[] ∈ {NoDuplicateMembers} multiple parameters (`filter=aaa&filter=bbb`)	Specify `NoDuplicateMembers` to return only the first log entry for each member. If `film` is not provided, only recent Log Entries will be returned (i.e. entries logged in the past 30 days). `NoDuplicateMembers` is only available when using these sort orders: `WhenAdded`, `Date`, `ReviewPopularity*`. You may not use `NoDuplicateMembers` with `filmMemberRelationship`, `filmDecade`, `filmYear`, `genre`, `tagCode`, `service`, or `where` except `HasDiaryDate`, `HasReview`, `Clean`, and/or `NoSpoilers`.

Response

200	Success	LogEntriesResponse
404	Film or Member not found

POST /log-entries

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

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

Request

LogEntryCreationRequest

Response

201	Success	LogEntry
204	No action was taken, as the log entry already exists
400	Bad request
401	There is no authenticated member
404	The film was not found

DELETE /log-entry/{id}

Delete a log entry by ID.

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

Parameters

id Required

path

string

The LID of the log entry.

Response

204	Success
400	Bad request
401	There is no authenticated member
403	The authenticated member is not authorized to delete this log entry
404	No log entry matches the specified ID

GET /log-entry/{id}

Get details about a log entry by ID.

Parameters

id Required

path

string

The LID of the log entry.

Response

200	Success	LogEntry
404	No log entry matches the specified ID

PATCH /log-entry/{id}

Update a log entry by ID.

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

Request

LogEntryUpdateRequest

Parameters

id Required

path

string

The LID of the log entry.

Response

200	Success	ReviewUpdateResponse
400	Bad request
401	There is no authenticated member, or the authenticated member does not own the resource
404	No log entry matches the specified ID

GET /log-entry/{id}/comments

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

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

Parameters

id Required	path	string	The LID of the log entry.
cursor	query	string	The pagination cursor.
perPage	query	integer	The number of items to include per page (default is `20`, maximum is `100`).
sort	query	enum ∈ {Date, DateLatestFirst, Updates}	Defaults to `Date`. The `Updates` sort order returns newest content first. Use this to get the most recently posted or edited comments, and pass `includeDeletions=true` to remain consistent in the case where a comment has been deleted.
includeDeletions	query	boolean	Use this to discover any comments that were deleted.

Response

200	Success	ReviewCommentsResponse
404	No log entry matches the specified ID

POST /log-entry/{id}/comments

Create a comment on a review.

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

Request

CommentCreationRequest

Parameters

id Required

path

string

The LID of the log entry.

Response

201	Success	ReviewComment
204	A comment with the same message already exists (no action was taken)
400	Bad request
401	There is no authenticated member
403	The authenticated member is not authorized to comment on this review
404	No film matches the specified ID

GET /log-entry/{id}/me

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

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

Parameters

id Required

path

string

The LID of the log entry.

Response

200	Success	ReviewRelationship
401	There is no authenticated member
404	No log entry matches the specified ID

PATCH /log-entry/{id}/me

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

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

Request

ReviewRelationshipUpdateRequest

Parameters

id Required

path

string

The LID of the log entry.

Response

200	Success	ReviewRelationshipUpdateResponse
401	There is no authenticated member
403	The authenticated member is not authorized to like or subscribe to this review
404	No log entry matches the specified ID

POST /log-entry/{id}/report

Report a log entry’s review by ID.

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

Request

ReportReviewRequest

Parameters

id Required

path

string

The LID of the log entry.

Response

204	Success
401	There is no authenticated member
404	No log entry matches the specified ID

GET /log-entry/{id}/statistics

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

Parameters

id Required

path

string

The LID of the log entry.

Response

200	Success	ReviewStatistics
404	No log entry matches the specified ID

GET /me

Get details about the authenticated member.

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

Response

200	Success	MemberAccount
401	There is no authenticated member

PATCH /me

Update the profile settings for the authenticated member.

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

Request

MemberSettingsUpdateRequest

Response

200	Success	MemberSettingsUpdateResponse
400	Bad request
401	There is no authenticated member

GET /me/check-tag

Check whether a tag is being merged before update.

Request

TagCheckRequest

Response

200	Success
204	successful operation	TagCheckResponse
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.

Request

TagDeleteRequest

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).

Request

DeregisterPushNotificationsRequest

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).

Request

DisableAccountRequest

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).

Request

RegisterPushNotificationsRequest

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.

Request

TagUpdateRequest

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	Member
404	No member matches the specified ID, or the member has opted out of appearing in the API

GET /member/{id}/activity

A cursored window over the activity for a member.

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

Parameters

id Required	path	string	The LID of the member.
cursor	query	string	The pagination cursor.
perPage	query	integer	The number of items to include per page (default is `20`, maximum is `100`).
include	query	enum[] ∈ {ReviewActivity, ReviewCommentActivity, ReviewLikeActivity, ListActivity, ListCommentActivity, ListLikeActivity, StoryActivity, DiaryEntryActivity, FilmRatingActivity, FilmWatchActivity, FilmLikeActivity, WatchlistActivity, FollowActivity, RegistrationActivity, InvitationAcceptedActivity} multiple parameters (`include=aaa&include=bbb`)	Only supported for paying members.Use `include` to specify the subset of activity to be returned. If neither `include` nor `exclude` is set, the activity types included depend on the `where` parameter:If `where=OwnActivity` is specified, all activity except `FilmLikeActivity`, `FilmWatchActivity` and `InvitationAcceptedActivity` is included.Otherwise all activity except `FilmLikeActivity`, `FilmWatchActivity`, `FilmRatingActivity`, `FollowActivity`, `RegistrationActivity` and `InvitationAcceptedActivity` is included.These defaults mimic those shown on the website.
exclude	query	enum[] ∈ {ReviewActivity, ReviewCommentActivity, ReviewLikeActivity, ListActivity, ListCommentActivity, ListLikeActivity, StoryActivity, DiaryEntryActivity, FilmRatingActivity, FilmWatchActivity, FilmLikeActivity, WatchlistActivity, FollowActivity, RegistrationActivity, InvitationAcceptedActivity} multiple parameters (`exclude=aaa&exclude=bbb`)	Only supported for paying members.DEPRECATED Use `include` instead.
where	query	enum[] ∈ {OwnActivity, NotOwnActivity, IncomingActivity, NotIncomingActivity, NetworkActivity} multiple parameters (`where=aaa&where=bbb`)	Use `where` to reduce the subset of activity to be returned. If `where` is not set, all default activity types relating to the member are returned. If multiple values are supplied, only activity matching all terms will be returned, e.g. `where=OwnActivity&where=NotIncomingActivity` will return all activity by the member except their comments on their own lists and reviews. `NetworkActivity` is activity performed either by the member or their followers. Use `where=NetworkActivity&where=NotOwnActivity` to only see activity from followers. If you don’t specify any of `NetworkActivity`, `OwnActivity` or `NotIncomingActivity`, you will receive activity related to the member’s content from members outside their network (e.g. comments and likes on the member’s lists and reviews).
adult	query	boolean	Whether to include activity related to adult content. Default to `false`.

Response

200	Success	ActivityResponse
404	No member matches the specified ID, or the member has opted out of appearing in the API

GET /member/{id}/list-tags

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

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

Parameters

id Required	path	string	The LID of the member.
input	query	string	A case-insensitive prefix match. E.g. “pro” will match “pro”, “project” and “Professional”. An empty `input` will match all tags.

Response

200	Success	TagsResponse
404	No member matches the specified ID, or the member has opted out of appearing in the API

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

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

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

Parameters

id Required	path	string	The LID of the member.
input	query	string	A case-insensitive prefix match. E.g. “pro” will match “pro”, “project” and “Professional”. An empty `input` will match all tags.

Response

200	Success	MemberTagsResponse
404	No member matches the specified ID, or the member has opted out of appearing in the API

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

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

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

Parameters

id Required	path	string	The LID of the member.
input	query	string	A case-insensitive prefix match. E.g. “pro” will match “pro”, “project” and “Professional”. An empty `input` will match all tags.

Response

200	Success	MemberTagsResponse
404	No member matches the specified ID, or the member has opted out of appearing in the API

GET /member/{id}/me

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

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

Parameters

id Required

path

string

The LID of the other member.

Response

200	Success	MemberRelationship
401	There is no authenticated member
404	No member matches the specified ID, or the member has opted out of appearing in the API

PATCH /member/{id}/me

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

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

Request

MemberRelationshipUpdateRequest

Parameters

id Required

path

string

The LID of the other member.

Response

200	Success	MemberRelationshipUpdateResponse
401	There is no authenticated member
404	No member matches the specified ID, or the member has opted out of appearing in the API

POST /member/{id}/report

Report a member by ID.

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

Request

ReportMemberRequest

Parameters

id Required

path

string

The LID of the member.

Response

204	Success
401	There is no authenticated member
404	No member matches the specified ID, or the member has opted out of appearing in the API

GET /member/{id}/review-tags

DEPRECATED Please use /log-entry-tags

Parameters

id Required	path	string	The LID of the member.
input	query	string	A case-insensitive prefix match. E.g. “pro” will match “pro”, “project” and “Professional”. An empty `input` will match all tags.

Response

200	Success	TagsResponse
404	No member matches the specified ID, or the member has opted out of appearing in the API

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

DEPRECATED Please use /log-entry-tags instead

Parameters

id Required	path	string	The LID of the member.
input	query	string	A case-insensitive prefix match. E.g. “pro” will match “pro”, “project” and “Professional”. An empty `input` will match all tags.

Response

200	Success	MemberTagsResponse
404	No member matches the specified ID, or the member has opted out of appearing in the API

GET /member/{id}/statistics

Get statistical data about a member by ID.

Parameters

id Required

path

string

The LID of the member.

Response

200	Success	MemberStatistics
404	No member matches the specified ID, or the member has opted out of appearing in the API

GET /member/{id}/watchlist

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

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

Parameters

id Required	path	string	The LID of the member.
cursor	query	string	The pagination cursor.
perPage	query	integer	The number of items to include per page (default is `20`, maximum is `100`).
filmId	query	string[] multiple parameters (`filmId=aaa&filmId=bbb`)	Specify up to 100 Letterboxd IDs or TMDB IDs prefixed with `tmdb:`, or IMDB IDs prefixed with `imdb:`
genre	query	string	Specify the LID of a genre to limit films to those within the specified genre.
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	string[] multiple parameters (`includeGenre=aaa&includeGenre=bbb`)	Specify the LID of up to 100 genres to limit films to those within all of the specified genres.
excludeGenre	query	string[] multiple parameters (`excludeGenre=aaa&excludeGenre=bbb`)	Specify the LID of up to 100 genres to limit films to those within none of the specified genres.
country	query	string	Specify the ISO 3166-1 defined code of the country to limit films to those produced 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} multiple parameters (`where=aaa&where=bbb`)	Specify one or more values to limit the list of films accordingly.
member	query	string	Specify the LID of a member to limit the returned films according to the value set in `memberRelationship` or to access the `MemberRating*` sort options.
memberRelationship	query	enum ∈ {Ignore, Watched (default), NotWatched, Liked, NotLiked, Rated, NotRated, InWatchlist, NotInWatchlist, Favorited}	Must be used in conjunction with `member`. Defaults to `Watched`. Specify the type of relationship to limit the returned films accordingly. Use `Ignore` if you only intend to specify the member for use with `sort=MemberRating*`.
includeFriends	query	enum ∈ {None (default), All, Only}	Must be used in conjunction with `member`. Defaults to `None`, which only returns films from the member’s account. Use `Only` to return films from the member’s friends, and `All` to return films from both the member and their friends.
tag	query	string	DEPRECATED Use `tagCode` instead.
tagCode	query	string	Specify a tag code to limit the returned films to those tagged accordingly.
tagger	query	string	Must be used with `tagCode`. Specify the LID of a member to focus the tag filter on the member.
includeTaggerFriends	query	enum ∈ {None (default), All, Only}	Must be used in conjunction with `tagger`. Defaults to `None`, which filters tags set by the member. Use `Only` to filter tags set by the member’s friends, and `All` to filter tags set by both the member and their friends.
sort	query	enum ∈ {Added (default), DateLatestFirst, DateEarliestFirst, Shuffle, FilmName, OwnerRatingHighToLow, OwnerRatingLowToHigh, AuthenticatedMemberRatingHighToLow, AuthenticatedMemberRatingLowToHigh, MemberRatingHighToLow, MemberRatingLowToHigh, AverageRatingHighToLow, AverageRatingLowToHigh, ReleaseDateLatestFirst, ReleaseDateEarliestFirst, FilmDurationShortestFirst, FilmDurationLongestFirst, FilmPopularity, RatingHighToLow, RatingLowToHigh, FilmPopularityThisWeek, FilmPopularityThisMonth, FilmPopularityThisYear}	The order in which the entries should be returned. Defaults to `Added`, which is the order that the films were added to the watchlist, most recent first.The `AuthenticatedMember` values are only available to signed-in members.The `MemberRating` values must be used in conjunction with `member` and are only available when specifying a single member (i.e. `IncludeFriends=None`).DEPRECATED The `FilmPopularityThisWeek`, `FilmPopularityThisMonth` and `FilmPopularityThisYear` options are deprecated, and have never worked. The `Rating` options are deprecated in favor of `AverageRating*`.

Response

200	Success	FilmsResponse
403	The specified member’s watchlist is private
404	No member matches the specified ID, or the member has opted out of appearing in the API

GET /members

A cursored window over the list of members.

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

Parameters

cursor	query	string	The pagination cursor.
perPage	query	integer	The number of items to include per page (default is `20`, maximum is `100`).
sort	query	enum ∈ {Date (default), Name, MemberPopularity, MemberPopularityThisWeek, MemberPopularityThisMonth, MemberPopularityThisYear, MemberPopularityWithFriends, MemberPopularityWithFriendsThisWeek, MemberPopularityWithFriendsThisMonth, MemberPopularityWithFriendsThisYear}	Defaults to `Date`, which has different semantics based on the request:When `review` is specified, members who most recently liked the review appear first.When `list` is specified, members who most recently liked the list appear first.When `film` is specified and `filmRelationship=Watched`, members who most recently watched the film appear first.When `film` is specified and `filmRelationship=Liked`, members who most recently liked the film appear first.When `film` is specified and `filmRelationship=InWatchlist`, members who most recently added the film to their watchlist appear first.When `member` is specified and `memberRelationship=IsFollowing`, most recently followed members appear first.When `member` is specified and `memberRelationship=IsFollowedBy`, most recent followers appear first.Otherwise, members who most recently joined the site appear first.The `*WithFriends` values are only available to authenticated members and consider popularity amongst the member’s friends.
member	query	string	Specify the LID of a member to return members who follow or are followed by 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.

Response

200

Success

MembersResponse

GET /members/pronouns

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

Response

200

Success

PronounsResponse

POST /members/register

Create a new account.

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

Request

RegisterRequest

Response

201	Success	Member
400	The username was already taken or is invalid.

GET /news

Get recent news from the Letterboxd editors.

Parameters

cursor	query	string	The pagination cursor.
perPage	query	integer	The number of items to include per page (default is `20`, maximum is `100`).

Response

200

Success

NewsResponse

GET /search

Parameters

cursor	query	string	The pagination cursor.
perPage	query	integer	The number of items to include per page (default is `20`, maximum is `100`).
input Required	query	string	The word, partial word or phrase to search for.
searchMethod	query	enum ∈ {FullText (default), Autocomplete, 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} multiple parameters (`include=aaa&include=bbb`)	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`.

Response

200

successful operation

SearchResponse

GET /stories

A cursored window over a list of stories.

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

Parameters

cursor	query	string	The pagination cursor.
perPage	query	integer	The number of items to include per page (default is `20`, maximum is `100`).
sort	query	enum ∈ {WhenUpdatedLatestFirst (default), WhenUpdatedEarliestFirst, WhenPublishedLatestFirst, WhenPublishedEarliestFirst, WhenCreatedLatestFirst, WhenCreatedEarliestFirst, StoryTitle}	Defaults to `WhenUpdatedLatestFirst`, which returns stories that were most recently created/updated first.
member	query	string	Specify the LID of a member to return stories from that member’s account.
where	query	enum[] ∈ {Published, NotPublished} multiple parameters (`where=aaa&where=bbb`)	Specify `Published` to return the member’s stories that have been made public. Note that unpublished stories for members other than the authenticated member are never returned. Specify `NotPublished` to return the authenticated member’s stories that have not been made public.

Response

200	Success	StoriesResponse
400	Bad request
404	No film, member, tag or list matches the specified ID.

GET /story/{id}

Get details of a story by ID.

Parameters

id Required

path

string

The LID of the story.

Response

200	Success	Story
404	No story matches the specified ID

Definitions

AbstractActivity

Properties

type Discriminator

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

The type of activity.

member

MemberSummary

The member associated with the activity.

whenCreated

string

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

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

AbstractComment

Properties

type Discriminator	enum[] ∈ {ListComment, ReviewComment}	The type of comment.
id	string	The LID of the comment/reply.
member	MemberSummary	The member who posted the comment.
whenCreated	string	ISO 8601 format with UTC timezone, i.e. `YYYY-MM-DDThh:mm:ssZ` "1997-08-29T07:14:00Z"
whenUpdated	string	ISO 8601 format with UTC timezone, i.e. `YYYY-MM-DDThh:mm:ssZ` "1997-08-29T07:14:00Z"
commentLbml	string	The message portion of the comment in LBML. May contain the following HTML tags: `<br>` `<strong>` `<em>` `<b>` `<i>` `<a href="">` `<blockquote>`.
removedByAdmin	boolean	If Letterboxd moderators have removed the comment from the site, `removedByAdmin` will be true and `comment` will not be included.
removedByContentOwner	boolean	If the content owner has removed the comment from the site, `removedByContentOwner` will be true and `comment` will not be included.
deleted	boolean	If the comment owner has removed the comment from the site, `deleted` will be true and `comment` will not be included.
blocked	boolean	If the authenticated member has blocked the commenter, `blocked` will be true and `comment` will not be included.
blockedByOwner	boolean	If the content owner has blocked the commenter, `blockedByOwner` will be true and `comment` will not be included.
editableWindowExpiresIn	integer	If the authenticated member posted this comment, and the comment is still editable, this value shows the number of seconds remaining until the editing window closes.
comment	string	The message portion of the comment formatted as HTML.

AbstractSearchItem

Properties

type Discriminator	enum[] ∈ {ContributorSearchItem, FilmSearchItem, ListSearchItem, MemberSearchItem, ReviewSearchItem, TagSearchItem, StorySearchItem, ArticleSearchItem, PodcastSearchItem}	The type of the search result.
score	number	A relevancy value that can be used to order results.

AccessToken

Properties

access_token	string	The access token that grants the member access. Combine this with the `token_type` to form the `Authorization` header.
token_type	string	The type of the access token. Use value: `bearer`
refresh_token	string	The refresh token is used to obtain a new access token, after the access token expires, without needing to prompt the member for their credentials again. The refresh token only expires if it is explicitly invalidated by Letterboxd, in which case the member should be prompted for their credentials (or stored credentials used).
expires_in	integer	The number of seconds before the access token expires.
notBefore	integer
issuer	string
encodedToken	string

ActivityResponse

Properties

next	Cursor	The cursor to the next page of results.
items	AbstractActivity[]	The list of activity items.

AGoogleBillingSubscription

Properties

subscriptionDaysRemaining

integer

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

AListAddition

Properties

list	ListIdentifier	The list.
additions	integer	The number of films added to the list.

AListEntryOccurrence

Properties

rank	integer	If the list is ranked, this is the entry’s rank in the list, numbered from 1.
filmId	string	The film LID for this entry.

AListTopic

Properties

name	string	The topic name.
items	ListSummary[]	The list of featured lists for the topic.

AppleIAPSubscription

Properties

subscriptionDaysRemaining

integer

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

AppleIAPSubscriptionMessage

Properties

type	enum ∈ {Error, Success}	The type of message.
code	enum ∈ {SubscriptionAlreadyExpired, SubscriptionBelongsToAnotherMember, UnexpectedError}	The error message code.
title	string	The error message text in human-readable form.

AppleIAPSubscriptionRequest

Properties

receiptToken Required

string

The receipt token (Base-64 encoded).

AppleIAPSubscriptionResponse

Properties

data Required	AppleIAPSubscription	The response object.
messages Required	AppleIAPSubscriptionMessage[]	A list of messages the API client should show to the user.

ArticleSearchItem < AbstractSearchItem

Inherited Properties

score Inherited

number

A relevancy value that can be used to order results.

Properties

article

NewsItem

The article.

CommentCreationRequest

Properties

comment Required

string

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

CommentUpdateMessage

Properties

type	enum ∈ {Error, Success}	The type of message.
code	enum ∈ {MissingComment, CommentOnContentYouBlocked, CommentOnBlockedContent, CommentBan, CommentEditWindowExpired, CommentTooLong}	The error message code.
title	string	The error message text in human-readable form.

CommentUpdateRequest

Properties

comment Required

string

CommentUpdateResponse

Properties

data Required	AbstractComment	The response object.
messages Required	CommentUpdateMessage[]	A list of messages the API client should show to the user.

ContributionStatistics

Properties

type	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.
filmCount	integer	The number of films for this contribution type.

Contributor

Properties

id	string	The LID of the contributor.
name	string	The name of the contributor.
tmdbid	string	The ID of the contributor on TMDB, if known
statistics	ContributorStatistics	An array of the types of contributions made, with a count of films for each contribution type.
links	Link[]	A list of relevant URLs for this entity, on Letterboxd and external sites.

ContributorSearchItem < AbstractSearchItem

Inherited Properties

score Inherited

number

A relevancy value that can be used to order results.

Properties

contributor

Contributor

Details of the contributor.

ContributorStatistics

Properties

contributions

ContributionStatistics[]

The statistics for each contribution type.

ContributorSummary

Properties

id	string	The LID of the contributor.
name	string	The name of the contributor.
characterName	string	The character name if available (only if the contribution is as an `Actor`; see the `type` field in FilmContributions).
tmdbid	string	The ID of the contributor on TMDB, if known

CountriesResponse

Properties

items

Country[]

The list of countries.

Country

Properties

code	string	The ISO 3166-1 defined code of the country.
name	string	The name of the country.

Cursor

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

DeregisterPushNotificationsRequest

Properties

deviceId Required

string

The device ID.

DiaryDetails

Properties

diaryDate	string	The date the film was watched, if specified, in ISO 8601 format, i.e. `YYYY-MM-DD`
rewatch	boolean	Will be `true` if the member has indicated (or it can be otherwise determined) that the member has seen the film prior to this date.

DiaryEntryActivity < AbstractActivity

Inherited Properties

member Inherited

MemberSummary

The member associated with the activity.

whenCreated Inherited

string

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

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

Properties

diaryEntry

LogEntry

The log entry associated with this activity

DisableAccountRequest

Properties

currentPassword Required	string	The member’s current password.
mode	enum ∈ {Disable, Delete}	The disable account mode - defaults to 'Disable' if not specified.

Film

Properties

id	string	The LID of the film.
name	string	The title of the film.
originalName	string	The original title of the film, if it was first released with a non-English title.
sortingName	string	A modified version of the name that has been normalized for consistent sorting.
alternativeNames	string[]	The other names by which the film is known (including alternative titles and/or foreign translations).
releaseYear	integer	The year in which the film was first released.
directors	ContributorSummary[]	The list of directors for the film.
poster	Image	The film’s poster image (2:3 aspect ratio in multiple sizes). Will contain only a single obfuscated image if the `adult` flag is `true`.
adultPoster	Image	The film’s unobfuscated poster image (2:3 aspect ratio in multiple sizes), only populated if the `adult` flag is `true`, may contain adult content.
top250Position	integer	The film’s position in the official Letterboxd Top 250 list of narrative feature films, `null` if the film is not in the list.
adult	boolean	`true` if the film is in TMDb’s ‘Adult’ category.
reviewsHidden	boolean	`true` if reviews for the film are hidden due to a high volume of moderation traffic.
filmCollectionId	string	The LID of the collection containing this film.
links	Link[]	A list of relevant URLs for this entity, on Letterboxd and external sites.
relationships	MemberFilmRelationship[]	Relationships to the film for the authenticated member (if any) and other members where relevant.
genres	Genre[]	The film’s genres.
tagline	string	The tagline for the film.
description	string	A synopsis of the film.
runTime	integer	The film’s duration (in minutes).
backdrop	Image	The film’s backdrop image (16:9 ratio in multiple sizes).
backdropFocalPoint	number	The backdrop’s vertical focal point, expressed as a proportion of the image’s height, using values between `0.0` and `1.0`. Use when cropping the image into a shorter space, such as in the page for a film on the Letterboxd site.
trailer	FilmTrailer	The film’s trailer.
countries	Country[]	The film’s production countries.
originalLanguage	Language	The film’s original language.
languages	Language[]	The film’s spoken languages.
contributions	FilmContributions[]	The film’s contributors (director, cast and crew) grouped by discipline.
news	NewsItem[]	The related news items for the film.
recentStories	Story[]	The related recent stories for the film.
similarTo	FilmSummary[]	FIRST PARTY The other films most similar to the film.
themes	Theme[]	FIRST PARTY The film’s themes.
minigenres	Minigenre[]	FIRST PARTY The film’s minigenres.
nanogenres	Nanogenre[]	FIRST PARTY The film’s nanogenres.

FilmAvailability

Properties

service	enum ∈ {Amazon, AmazonVideo, AmazonPrime, iTunes, Netflix}	DEPRECATED Use `displayName` instead.
displayName	string	The name of the service.
icon	string	The URL of the thumbnail image for the service.
country	enum ∈ {AIA, ARE, ARG, ARM, ATG, AUS, AUT, AZE, BEL, BFA, BGR, BHR, BHS, BLR, BLZ, BMU, BOL, BRA, BRB, BRN, BWA, CAN, CHE, CHL, CHN, COL, CPV, CRI, CYM, CYP, CZE, DEU, DMA, DNK, DOM, ECU, EGY, ESP, EST, FIN, FJI, FRA, FSM, GBR, GHA, GMB, GNB, GRC, GRD, GTM, HKG, HND, HRV, HUN, IDN, IND, IRL, ISR, ITA, ISL, JOR, JPN, KAZ, KEN, KGZ, KHM, KNA, KOR, LAO, LBN, LKA, LTU, LUX, LVA, MAC, MDA, MEX, MLT, MNG, MOZ, MUS, MYS, NAM, NER, NGA, NIC, NLD, NOR, NPL, NZL, OMN, PAN, PER, PHL, PNG, POL, PRT, PRY, QAT, ROU, RUS, SAU, SGP, SLV, SVK, SVN, SWE, SWZ, THA, TJK, TKM, TTO, TUR, TWN, UGA, UKR, USA, UZB, VEN, VGB, VNM, ZAF, ZWE, GUF, YEM, KWT, LBY, MAR, DZA, TUN, GIB, SMR, MCO, LIE, URY, JAM, CIV, GNQ, GGY, SRB, PAK, PYF, LCA, SYC, IRQ, TCA, ZMB, SEN, TZA, AND, ALB, BIH, VAT}	The regional store for the service. Not all countries are supported on all services.
id	string	The unique ID (if any) for the film on this service.
url	string	The URL for the film on this service.
types	string[]	The types of the availability, possible options included buy, rent and stream
serviceCode	string	The code for the service.

FilmAvailabilityResponse

Properties

items

FilmAvailability[]

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

FilmCollection

Properties

id	string	The LID of the film collection.
name	string	The name of the collection.
films	FilmSummary[]	The list of films in the collection.
links	Link[]	A list of relevant URLs for this entity, on Letterboxd and external sites.

FilmContribution

Properties

type	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.
film	FilmSummary	The film.
characterName	string	The name of the character (only when `type` is `Actor`).

FilmContributions

Properties

type	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.
contributors	ContributorSummary[]	The list of contributors of the specified type for the film.

FilmContributionsCollection

Properties

contributions

FilmContributions[]

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

FilmContributionsResponse

Properties

next	Cursor	The cursor to the next page of results.
items	FilmContribution[]	The list of contributions.
metadata	FilmContributorMetadata[]	Metadata about the contributor’s contributions.
relationships	FilmContributorMemberRelationship[]	The relationships to the contributor for the members referenced in the request.

FilmContributorMemberRelationship

Properties

member	MemberSummary	The member.
relationships	FilmContributorRelationship[]	The relationship details.

FilmContributorMetadata

Properties

type	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.
data	FilmsMetadata	The details for this contribution type.

FilmContributorRelationship

Properties

type	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.
relationship	FilmsRelationship	The relationship the member has with the (filtered) films.

FilmIdentifier

Properties

string

The LID of the film.

FilmLikeActivity < AbstractActivity

Inherited Properties

member Inherited

MemberSummary

The member associated with the activity.

whenCreated Inherited

string

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

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

Properties

film

FilmSummary

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

FilmRatingActivity < AbstractActivity

Inherited Properties

member Inherited

MemberSummary</