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

oauth2

The Letterboxd API uses standard OAuth2 Password, Client Credentials, Authorization Code and Refresh Token authorization flows to grant access via an access token. The Password flow is for first-party use only. Third-party API consumers must use the Client Credentials or Authorization Code flows. Client Credentials returns publicly available data (learn more), while Authorization Code must be used for any operation that requires member authentication, such as accessing private content or modifying a member’s data (learn more). When generating or refreshing access tokens, make a form request to the /auth/token endpoint with Content-Type: application/x-www-form-urlencoded and Accept: application/json headers.

An access token must be included with all requests that indicate they required oauth2 security using an Authorization: Bearer [TOKEN] request header.

You must refresh an access token before it expires, according to the expires_in attribute of the access token. If the access token expires, you’ll need to repeat the relevant auth flow to generate a new token.

Revocation

Access tokens and refresh tokens should be revoked when the user signs out. The Letterboxd API uses standard OAuth2 Token Revocation.

Scopes

A scope is a security requirement that must be met before you can use an endpoint. Scopes are tied to an access token.

Some scopes are automatically granted based on the auth flow in use, and you do not need to request authorization from the member for these defaults. If you request additional scopes beyond the defaults, they will be displayed to the person using your app, and your app will be granted permission to these scopes if the person agrees to the level of account access being sought.

When requesting multiple scopes, they must be provided in the form of a space- or plus-delimited string. For example profile:modify content:modify or profile:modify+content:modify.

OpenID Connect

Letterboxd supports OpenID Connect (OIDC). To use OIDC, you must request the necessary scopes. Discovery information is available at Letterboxd’s openid-configuration endpoint.

Request signing

Letterboxd previously required signing on all API requests; this requirement has been removed. Legacy API implementers should switch to standard OAuth2 practices.

Client Credentials flow

The audience parameter mentioned in the linked OAuth documentation is not required when using our Client Credentials flow. grant_type, client_id and client_secret must all be sent.

URL encoding

All query and form parameters must be URL encoded. Particularly, when using the Authorization Code flow, remember to URL encode the redirect_uri parameter.

Password flow

Token URL https://api.letterboxd.com/api/v0/auth/token
Refresh URL https://api.letterboxd.com/api/v0/auth/token
Scopes
user:owner Must be the owner of the member account. This scope cannot be requested.
user Must be a Letterboxd member. This scope cannot be requested.
profile:private:view View profile information (including private information) for the member.
profile:modify Modify profile details for the member.
security:modify Modify security details for the member.
content:modify Modify content belonging to the member.
client:firstparty Must be a first-party client. This scope cannot be requested.
oauth:refresh Allowed to use refresh tokens. When requesting an access token, a refresh token will be provided.
openid Allows OIDC ID tokens to be created. OIDC will be used to verify the member’s identity.
profile OIDC ID tokens contain the member’s profile details, including username, display name, website link and bio content.
email OIDC ID tokens contain the member’s email address and an indication as to whether is has been validated.

Authorization code flow

Authorization URL https://api.letterboxd.com/api/v0/auth/authorize
Token URL https://api.letterboxd.com/api/v0/auth/token
Refresh URL https://api.letterboxd.com/api/v0/auth/token
Scopes
user:owner Must be the owner of the member account. This scope cannot be requested.
user Must be a Letterboxd member. This scope cannot be requested.
profile:private:view View profile information (including private information) for the member.
profile:modify Modify profile details for the member.
security:modify Modify security details for the member.
content:modify Modify content belonging to the member.
client:firstparty Must be a first-party client. This scope cannot be requested.
oauth:refresh Allowed to use refresh tokens. When requesting an access token, a refresh token will be provided.
openid Allows OIDC ID tokens to be created. OIDC will be used to verify the member’s identity.
profile OIDC ID tokens contain the member’s profile details, including username, display name, website link and bio content.
email OIDC ID tokens contain the member’s email address and an indication as to whether is has been validated.

Client credentials flow

Token URL https://api.letterboxd.com/api/v0/auth/token

Endpoints

Auth

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.

Operation ID
getLoginTokenRequest
Security
oauth2 user:owner
Response
200

Success

 LoginTokenResponse
400

Bad request

 ErrorResponse

application/json; charset=UTF-8

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.

Operation ID
getUploadUrl
Security
oauth2 user, client:firstparty
Response
200

Success

 UploadUrlResponse
400

Bad request

 ErrorResponse

application/json; charset=UTF-8

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

Operation ID
checkUsername
Security
oauth2
Parameters
username Required string query

The username to check.
Response
200

Success

 UsernameCheckResponse

application/json; charset=UTF-8

POST /auth/forgotten-password-request

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

Operation ID
forgottenPasswordRequest
Security
oauth2
Request

ForgottenPasswordRequest

application/json; charset=UTF-8

Response
204

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

Bad request

 ErrorResponse
429

Too many forgotten password requests have been received for this email address. Check the member’s spam/junk folder.

application/json; charset=UTF-8

Comments

POST /comment/{id}/report

Report a comment by ID.

Operation ID
reportComment
Security
oauth2 user, content:modify
Request

ReportCommentRequest

application/json; charset=UTF-8

Parameters
id Required string path

The LID of the comment/​reply.
Response
204

Success
404

No comment matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

PATCH /comment/{id}

Update the message portion of a comment.

Operation ID
updateComment
Security
oauth2 user, content:modify
Request

CommentUpdateRequest

application/json; charset=UTF-8

Parameters
id Required string path

The LID of the comment/​reply.
Response
200

Completed, possibly with messages

 CommentUpdateResponse
403

Not your comment

 ErrorResponse
404

No comment matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

DELETE /comment/{id}

Delete a comment.

Comments may be deleted by their owner, or by the owner of the thread to which they are posted.

Operation ID
deleteComment
Security
oauth2 user, content:modify
Parameters
id Required string path

The LID of the comment/​reply.
Response
204

Success
400

Bad request

 ErrorResponse
403

The window for deleting this comment has expired

 ErrorResponse
404

No comment matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

Contributors

GET /contributor/{id}

Get details about a film contributor by ID or TMDb ID.

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

Operation ID
contributor
Security
oauth2
Parameters
id Required string path

The LID of the contributor or the TMDb ID prefixed with tmdb: e.g. tmdb:3
Response
200

Success

 Contributor
404

No contributor matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

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

Operation ID
contributions
Security
oauth2
Parameters
id Required string path

The LID of the contributor.
cursor string query

The pagination cursor.
perPage int32 (number) query

The number of items to include per page (default is 20, maximum is 100).
filmId Examples string[]
(exploded form-style)
query

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

 
filmId=b8wK&filmId=imdb:tt1396484
genre string query

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

FIRST PARTY Specify the LID of a film to limit films to those similar to the specified film.
theme string query

FIRST PARTY Specify the code of a theme to limit films to those within the specified theme.
minigenre string query

FIRST PARTY Specify the code of a minigenre to limit films to those within the specified minigenre.
nanogenre string query

FIRST PARTY Specify the code of a nanogenre to limit films to those within the specified nanogenre.
includeGenre string[]
(exploded form-style)
query

Specify the LID of up to 100 genres to limit films to those within all of the specified genres.
excludeGenre string[]
(exploded form-style)
query

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

Specify the ISO 3166-1 defined code of the country to limit films to those produced by the specified country.
language string query

Specify the ISO 639-1 defined code of the language to limit films to those using the specified spoken language.
decade Examples int32 (number) query

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

 
1990
year Examples int32 (number) query

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

 
1994
service string query

Specify the ID of a supported service to limit films to those available from that service. The list of available services can be found by using the /films/film-services endpoint.
availabilityType string[]
(exploded form-style)
query

Specify the availability types to limit films to those with those availability types. The list of availability types can be found by using the /films/availability-types endpoint.
exclusive boolean query

Set to true to limit films to those available on only one service.
unavailable boolean query

Set to true to limit films to those not available on any services.
includeOwned boolean query

Set to true to include films that the user owns.
negate boolean query

Set to true to invert the current service filtering options.
where Examples FilmWhereClause[]
(exploded form-style)
query

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

 
where=Watched&where=Released
memberMinRating number query

Allowable values are between 0.5 and 5.0, with increments of 0.5. If set, limits the returned films for the member to those with a rating equal to or higher than the specified rating.
memberMaxRating number query

Allowable values are between 0.5 and 5.0, with increments of 0.5. If set, limits the returned films for the member to those with a rating equal to or lower than the specified rating.
member string query

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 FilmMemberRelationship query

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 IncludeFriends query

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 DEPRECATED string query

Use tagCode instead.
tagCode string query

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

Must be used with tagCode or includeTags. Specify the LID of a member to focus the tag filter on the member.
includeTaggerFriends IncludeFriends query

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.
includeTags string[]
(exploded form-style)
query

Specify a list of tag codes to limit the returned films to those with all the specified tags.
excludeTags string[]
(exploded form-style)
query

Specify a list of tag codes to limit the returned films to those with none of the specified tags.
sort enum ∈ { Billing, FilmName, ReleaseDateLatestFirst, ReleaseDateEarliestFirst, AuthenticatedMemberRatingHighToLow, AuthenticatedMemberRatingLowToHigh, MemberRatingHighToLow, MemberRatingLowToHigh, AverageRatingHighToLow, AverageRatingLowToHigh, RatingHighToLow, RatingLowToHigh, FilmDurationShortestFirst, FilmDurationLongestFirst, FilmPopularity, FilmPopularityThisWeek, FilmPopularityThisMonth, FilmPopularityThisYear } query

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 ContributionType query

The type of contribution.
Response
200

Success

 FilmContributionsResponse
404

No contributor matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

Film collections

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.

Operation ID
getFilmCollectionDetails
Security
oauth2
Parameters
id Required string path

The LID of the film collection.
filmId Examples string[]
(exploded form-style)
query

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

 
filmId=b8wK&filmId=imdb:tt1396484
genre string query

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

FIRST PARTY Specify the LID of a film to limit films to those similar to the specified film.
theme string query

FIRST PARTY Specify the code of a theme to limit films to those within the specified theme.
minigenre string query

FIRST PARTY Specify the code of a minigenre to limit films to those within the specified minigenre.
nanogenre string query

FIRST PARTY Specify the code of a nanogenre to limit films to those within the specified nanogenre.
includeGenre string[]
(exploded form-style)
query

Specify the LID of up to 100 genres to limit films to those within all of the specified genres.
excludeGenre string[]
(exploded form-style)
query

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

Specify the ISO 3166-1 defined code of the country to limit films to those produced by the specified country.
language string query

Specify the ISO 639-1 defined code of the language to limit films to those using the specified spoken language.
decade Examples int32 (number) query

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

 
1990
year Examples int32 (number) query

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

 
1994
service string query

Specify the ID of a supported service to limit films to those available from that service. The list of available services can be found by using the /films/film-services endpoint.
availabilityType string[]
(exploded form-style)
query

Specify the availability types to limit films to those with those availability types. The list of availability types can be found by using the /films/availability-types endpoint.
exclusive boolean query

Set to true to limit films to those available on only one service.
unavailable boolean query

Set to true to limit films to those not available on any services.
includeOwned boolean query

Set to true to include films that the user owns.
negate boolean query

Set to true to invert the current service filtering options.
where Examples FilmWhereClause[]
(exploded form-style)
query

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

 
where=Watched&where=Released
memberMinRating number query

Allowable values are between 0.5 and 5.0, with increments of 0.5. If set, limits the returned films for the member to those with a rating equal to or higher than the specified rating.
memberMaxRating number query

Allowable values are between 0.5 and 5.0, with increments of 0.5. If set, limits the returned films for the member to those with a rating equal to or lower than the specified rating.
member string query

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 FilmMemberRelationship query

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 IncludeFriends query

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 DEPRECATED string query

Use tagCode instead.
tagCode string query

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

Must be used with tagCode or includeTags. Specify the LID of a member to focus the tag filter on the member.
includeTaggerFriends IncludeFriends query

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.
includeTags string[]
(exploded form-style)
query

Specify a list of tag codes to limit the returned films to those with all the specified tags.
excludeTags string[]
(exploded form-style)
query

Specify a list of tag codes to limit the returned films to those with none of the specified tags.
sort enum ∈ { FilmName, ReleaseDateLatestFirst, ReleaseDateEarliestFirst, AuthenticatedMemberRatingHighToLow, AuthenticatedMemberRatingLowToHigh, MemberRatingHighToLow, MemberRatingLowToHigh, AverageRatingHighToLow, AverageRatingLowToHigh, FilmDurationShortestFirst, FilmDurationLongestFirst, FilmPopularity, FilmPopularityThisWeek, FilmPopularityThisMonth, FilmPopularityThisYear, FilmPopularityWithFriends, FilmPopularityWithFriendsThisWeek, FilmPopularityWithFriendsThisMonth, FilmPopularityWithFriendsThisYear } query

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

 ErrorResponse

application/json; charset=UTF-8

Films

GET /film/{id}

Get details about a film by ID or TMDb ID. Supports an optional member ID to honor custom-poster settings.

Operation ID
getFilmDetails
Security
oauth2
Parameters
id Required string path

The LID of the film or the TMDb ID prefixed with tmdb: e.g. tmdb:11.
member string query

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

 ErrorResponse

application/json; charset=UTF-8

GET /film/{id}/availability

FIRST PARTY Get availability data for a film by ID.

Operation ID
filmAvailability
Security
oauth2
Parameters
id Required string path

The LID of the film.
Response
200

Success

 FilmAvailabilityResponse
404

No film matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

GET /film/{id}/friends

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

Operation ID
friendRelationships
Security
oauth2 user
Parameters
id Required string path

The LID of the film.
Response
200

Success

 FriendFilmRelationshipsResponse
404

No film matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

GET /film/{id}/me

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

Operation ID
myRelationshipToFilm
Security
oauth2 user
Parameters
id Required string path

The LID of the film.
Response
200

Success

 FilmRelationship
404

No film matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

GET /film/{id}/members

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

Operation ID
memberRelationships
Security
oauth2
Parameters
id Required string path

The LID of the film.
cursor string query

The pagination cursor.
perPage int32 (number) query

The number of items to include per page (default is 20, maximum is 100).
sort enum ∈ { Date, Name, MemberPopularity, MemberPopularityThisWeek, MemberPopularityThisMonth, MemberPopularityThisYear, MemberPopularityWithFriends, MemberPopularityWithFriendsThisWeek, MemberPopularityWithFriendsThisMonth, MemberPopularityWithFriendsThisYear } query

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 string query

Specify the LID of a member to return members who follow or are followed by that member.
memberRelationship enum ∈ { IsFollowing, IsFollowedBy } query

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 FilmMemberRelationship query

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
400

Bad request

 ErrorResponse
404

No film matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

GET /film/{id}/statistics

Get statistical data about a film by ID.

Operation ID
filmStatistics
Security
oauth2
Parameters
id Required string path

The LID of the film.
member string query

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

 ErrorResponse

application/json; charset=UTF-8

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.

Operation ID
films
Security
oauth2
Parameters
cursor string query

The pagination cursor.
perPage int32 (number) query

The number of items to include per page (default is 20, maximum is 100).
filmId Examples string[]
(exploded form-style)
query

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

 
filmId=b8wK&filmId=imdb:tt1396484
genre string query

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

FIRST PARTY Specify the LID of a film to limit films to those similar to the specified film.
theme string query

FIRST PARTY Specify the code of a theme to limit films to those within the specified theme.
minigenre string query

FIRST PARTY Specify the code of a minigenre to limit films to those within the specified minigenre.
nanogenre string query

FIRST PARTY Specify the code of a nanogenre to limit films to those within the specified nanogenre.
includeGenre string[]
(exploded form-style)
query

Specify the LID of up to 100 genres to limit films to those within all of the specified genres.
excludeGenre string[]
(exploded form-style)
query

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

Specify the ISO 3166-1 defined code of the country to limit films to those produced by the specified country.
language string query

Specify the ISO 639-1 defined code of the language to limit films to those using the specified spoken language.
decade Examples int32 (number) query

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

 
1990
year Examples int32 (number) query

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

 
1994
service string query

Specify the ID of a supported service to limit films to those available from that service. The list of available services can be found by using the /films/film-services endpoint.
availabilityType string[]
(exploded form-style)
query

Specify the availability types to limit films to those with those availability types. The list of availability types can be found by using the /films/availability-types endpoint.
exclusive boolean query

Set to true to limit films to those available on only one service.
unavailable boolean query

Set to true to limit films to those not available on any services.
includeOwned boolean query

Set to true to include films that the user owns.
negate boolean query

Set to true to invert the current service filtering options.
where Examples FilmWhereClause[]
(exploded form-style)
query

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

 
where=Watched&where=Released
memberMinRating number query

Allowable values are between 0.5 and 5.0, with increments of 0.5. If set, limits the returned films for the member to those with a rating equal to or higher than the specified rating.
memberMaxRating number query

Allowable values are between 0.5 and 5.0, with increments of 0.5. If set, limits the returned films for the member to those with a rating equal to or lower than the specified rating.
member string query

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 FilmMemberRelationship query

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 IncludeFriends query

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 DEPRECATED string query

Use tagCode instead.
tagCode string query

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

Must be used with tagCode or includeTags. Specify the LID of a member to focus the tag filter on the member.
includeTaggerFriends IncludeFriends query

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.
includeTags string[]
(exploded form-style)
query

Specify a list of tag codes to limit the returned films to those with all the specified tags.
excludeTags string[]
(exploded form-style)
query

Specify a list of tag codes to limit the returned films to those with none of the specified tags.
sort enum ∈ { FilmName, DateLatestFirst, DateEarliestFirst, ReleaseDateLatestFirst, ReleaseDateEarliestFirst, AuthenticatedMemberRatingHighToLow, AuthenticatedMemberRatingLowToHigh, AuthenticatedMemberBasedOnLiked, AuthenticatedMemberRelatedToLiked, MemberRatingHighToLow, MemberRatingLowToHigh, AverageRatingHighToLow, AverageRatingLowToHigh, RatingHighToLow, RatingLowToHigh, FilmDurationShortestFirst, FilmDurationLongestFirst, BestMatch, FilmPopularity, FilmPopularityThisWeek, FilmPopularityThisMonth, FilmPopularityThisYear, FilmPopularityWithFriends, FilmPopularityWithFriendsThisWeek, FilmPopularityWithFriendsThisMonth, FilmPopularityWithFriendsThisYear } query

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*.
countItems boolean query

Set to true to include the total count of films matching this request. This is the total count of all films matching the request, not just the count of films returned on this page.
Response
200

Success

 FilmsResponse
400

Bad request

 ErrorResponse

application/json; charset=UTF-8

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.

Operation ID
autocompleteFilms
Security
oauth2
Parameters
perPage int32 (number) query

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

The word, partial word or phrase to match against.
adult boolean query

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

Success

 FilmsAutocompleteResponse

application/json; charset=UTF-8

GET /films/availability-types

Get a list of availability types supported by the /films endpoint.

Availability types are returned in alphabetical order.

Operation ID
getAvailabilityTypesList
Response
200

Success

 AvailabilityTypesResponse

application/json; charset=UTF-8

GET /films/countries

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

Countries are returned in alphabetical order.

Operation ID
getCountryList
Security
oauth2
Response
200

Success

 CountriesResponse

application/json; charset=UTF-8

GET /films/film-services

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

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

Operation ID
getFilmServiceList
Security
oauth2
Response
200

Success

 FilmServicesResponse

application/json; charset=UTF-8

GET /films/genres

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

Genres are returned in alphabetical order.

Operation ID
getGenreList
Security
oauth2
Response
200

Success

 GenresResponse

application/json; charset=UTF-8

GET /films/languages

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

Languages are returned in alphabetical order.

Operation ID
getLanguageList
Security
oauth2
Response
200

Success

 LanguagesResponse

application/json; charset=UTF-8

POST /film/{id}/report

Report a film by ID.

Operation ID
report
Security
oauth2 user, content:modify
Request

ReportFilmRequest

application/json; charset=UTF-8

Parameters
id Required string path

The LID of the film.
Response
204

Success
400

Bad request

 ErrorResponse
404

No film matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

PATCH /film/{id}/me

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

Operation ID
updateMyRelationshipToFilm
Security
oauth2 user, content:modify
Request

FilmRelationshipUpdateRequest

application/json; charset=UTF-8

Parameters
id Required string path

The LID of the film.
Response
200

Success

 FilmRelationshipUpdateResponse
404

No film matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

Lists

GET /list/{id}

Get details of a list by ID.

Operation ID
getList
Security
oauth2
Parameters
id Required string path

The LID of the list.
Response
200

Success

 List
404

No list matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

GET /list/{id}/comments

A cursored window over the comments for a list.

Use the next cursor to move through the comments.

Operation ID
getListComments
Security
oauth2
Parameters
id Required string path

The LID of the list.
cursor string query

The pagination cursor.
perPage int32 (number) query

The number of items to include per page (default is 20, maximum is 100).
sort enum ∈ { Date, DateLatestFirst, Updates } query

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 boolean query

Use this to discover any comments that were deleted.
Response
200

Success

 ListCommentsResponse
404

No list matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

GET /list/{id}/entries

Get entries for a list by ID.

Operation ID
getEntries
Security
oauth2
Parameters
id Required string path

The LID of the list.
cursor string query

The pagination cursor.
perPage int32 (number) query

The number of items to include per page (default is 20, maximum is 100).
filmId Examples string[]
(exploded form-style)
query

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

 
filmId=b8wK&filmId=imdb:tt1396484
genre string query

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

FIRST PARTY Specify the LID of a film to limit films to those similar to the specified film.
theme string query

FIRST PARTY Specify the code of a theme to limit films to those within the specified theme.
minigenre string query

FIRST PARTY Specify the code of a minigenre to limit films to those within the specified minigenre.
nanogenre string query

FIRST PARTY Specify the code of a nanogenre to limit films to those within the specified nanogenre.
includeGenre string[]
(exploded form-style)
query

Specify the LID of up to 100 genres to limit films to those within all of the specified genres.
excludeGenre string[]
(exploded form-style)
query

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

Specify the ISO 3166-1 defined code of the country to limit films to those produced by the specified country.
language string query

Specify the ISO 639-1 defined code of the language to limit films to those using the specified spoken language.
decade Examples int32 (number) query

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

 
1990
year Examples int32 (number) query

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

 
1994
service string query

Specify the ID of a supported service to limit films to those available from that service. The list of available services can be found by using the /films/film-services endpoint.
availabilityType string[]
(exploded form-style)
query

Specify the availability types to limit films to those with those availability types. The list of availability types can be found by using the /films/availability-types endpoint.
exclusive boolean query

Set to true to limit films to those available on only one service.
unavailable boolean query

Set to true to limit films to those not available on any services.
includeOwned boolean query

Set to true to include films that the user owns.
negate boolean query

Set to true to invert the current service filtering options.
where Examples FilmWhereClause[]
(exploded form-style)
query

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

 
where=Watched&where=Released
memberMinRating number query

Allowable values are between 0.5 and 5.0, with increments of 0.5. If set, limits the returned films for the member to those with a rating equal to or higher than the specified rating.
memberMaxRating number query

Allowable values are between 0.5 and 5.0, with increments of 0.5. If set, limits the returned films for the member to those with a rating equal to or lower than the specified rating.
member string query

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 FilmMemberRelationship query

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 IncludeFriends query

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 DEPRECATED string query

Use tagCode instead.
tagCode string query

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

Must be used with tagCode or includeTags. Specify the LID of a member to focus the tag filter on the member.
includeTaggerFriends IncludeFriends query

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.
includeTags string[]
(exploded form-style)
query

Specify a list of tag codes to limit the returned films to those with all the specified tags.
excludeTags string[]
(exploded form-style)
query

Specify a list of tag codes to limit the returned films to those with none of the specified tags.
sort enum ∈ { ListRanking, WhenAddedToList, WhenAddedToListEarliestFirst, Shuffle, FilmName, OwnerRatingHighToLow, OwnerRatingLowToHigh, OwnerDiaryLatestFirst, OwnerDiaryEarliestFirst, AuthenticatedMemberRatingHighToLow, AuthenticatedMemberRatingLowToHigh, AuthenticatedMemberDiaryLatestFirst, AuthenticatedMemberDiaryEarliestFirst, AuthenticatedMemberBasedOnLiked, AuthenticatedMemberRelatedToLiked, MemberRatingHighToLow, MemberRatingLowToHigh, MemberDiaryLatestFirst, MemberDiaryEarliestFirst, AverageRatingHighToLow, AverageRatingLowToHigh, RatingHighToLow, RatingLowToHigh, ReleaseDateLatestFirst, ReleaseDateEarliestFirst, FilmDurationShortestFirst, FilmDurationLongestFirst, FilmPopularity, FilmPopularityThisWeek, FilmPopularityThisMonth, FilmPopularityThisYear } query

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

 ErrorResponse

application/json; charset=UTF-8

GET /list/{id}/me

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

Operation ID
myRelationshipToList
Security
oauth2 user
Parameters
id Required string path

The LID of the list.
Response
200

Success

 ListRelationship
404

No list matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

GET /list/{id}/statistics

Get statistical data about a list by ID.

Operation ID
getListStatistics
Security
oauth2
Parameters
id Required string path

The LID of the list.
Response
200

Success

 ListStatistics
404

No list matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

GET /lists

A cursored window over a list of lists.

Use the next cursor to move through the list.

Operation ID
lists
Security
oauth2
Parameters
cursor string query

The pagination cursor.
perPage int32 (number) query

The number of items to include per page (default is 20, maximum is 100).
sort enum ∈ { Date, WhenLiked, WhenPublishedLatestFirst, WhenPublishedEarliestFirst, WhenCreatedLatestFirst, WhenCreatedEarliestFirst, WhenAccessedLatestFirst, WhenAccessedEarliestFirst, ListName, ListPopularity, ListPopularityThisWeek, ListPopularityThisMonth, ListPopularityThisYear, ListPopularityWithFriends, ListPopularityWithFriendsThisWeek, ListPopularityWithFriendsThisMonth, ListPopularityWithFriendsThisYear } query

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 string query

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

Specify the LID of a list to return lists that were cloned from the list.
tag DEPRECATED string query

Use tagCode instead.
tagCode string query

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

Must be used with tagCode or includeTags. Specify the LID of a member to focus the tag filter on the member.
includeTaggerFriends IncludeFriends query

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.
includeTags string[]
(exploded form-style)
query

Specify a list of tag codes to limit the returned lists to those with all the specified tags.
excludeTags string[]
(exploded form-style)
query

Specify a list of tag codes to limit the returned lists to those with none of the specified tags.
member string query

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 ListMemberRelationship query

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 IncludeFriends query

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 ListWhereClause[]
(exploded form-style)
query

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 Examples array of enum ∈ { NoDuplicateMembers }
(exploded form-style)
query

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.

 
filter=NoDuplicateMembers
filmsOfNote string[]
(exploded form-style)
query

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

Success

 ListsResponse
400

Bad request

 ErrorResponse
403

The authenticated member does not own the resource (when requesting where=NotPublished).

 ErrorResponse
404

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

 ErrorResponse

application/json; charset=UTF-8

GET /lists/topics

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

Operation ID
topics
Security
oauth2
Response
200

Success

 TopicsResponse

application/json; charset=UTF-8

POST /list/{id}/comments

Create a comment on a list.

Operation ID
createListComment
Security
oauth2 user, content:modify
Request

CommentCreationRequest

application/json; charset=UTF-8

Parameters
id Required string path

The LID of the list.
Response
200

Success

 ListComment
400

Bad request

 ErrorResponse
403

The authenticated member is not authorized to comment on this list

 ErrorResponse
404

No list matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

POST /list/{id}/forget

Forget a shared list by ID.

Operation ID
forgetList
Security
oauth2 user, content:modify
Parameters
id Required string path

The LID of the list.
Response
204

Success
404

No list matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

POST /list/{id}/report

Report a list by ID.

Operation ID
reportList
Security
oauth2 user, content:modify
Request

ReportListRequest

application/json; charset=UTF-8

Parameters
id Required string path

The LID of the list.
Response
204

Success
400

Bad request

 ErrorResponse
404

No list matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

POST /lists

Create a list.

Operation ID
createList
Security
oauth2 user, content:modify
Request

ListCreationRequest

application/json; charset=UTF-8

Response
200

Success

 ListCreateResponse
400

Bad request

 ErrorResponse

application/json; charset=UTF-8

PATCH /list/{id}

Update a list by ID.

Operation ID
updateList
Security
oauth2 user, content:modify
Request

ListUpdateRequest

application/json; charset=UTF-8

Parameters
id Required string path

The LID of the list.
Response
200

Success

 ListUpdateResponse
400

Bad request

 ErrorResponse
403

Not your list

 ErrorResponse
404

No list matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

PATCH /list/{id}/me

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

Operation ID
updateMyRelationship
Security
oauth2 user, content:modify
Request

ListRelationshipUpdateRequest

application/json; charset=UTF-8

Parameters
id Required string path

The LID of the list.
Response
200

Success

 ListRelationshipUpdateResponse
404

No list matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

PATCH /lists

Add one or more films to one or more lists.

Operation ID
addToLists
Security
oauth2 user, content:modify
Request

ListAdditionRequest

application/json; charset=UTF-8

Response
200

Success

 ListAdditionResponse
400

Bad request

 ErrorResponse

application/json; charset=UTF-8

DELETE /list/{id}

Delete a list by ID.

Operation ID
deleteList
Security
oauth2 user, content:modify
Parameters
id Required string path

The LID of the list.
Response
204

Success
400

Bad request

 ErrorResponse
403

The authenticated member does not own the specified list

 ErrorResponse
404

No list matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

Log entries

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.

Operation ID
getLogEntries
Security
oauth2
Parameters
cursor string query

The pagination cursor.
perPage int32 (number) query

The number of items to include per page (default is 20, maximum is 100).
sort enum ∈ { WhenAdded, 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 } query

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

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 string query

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 ReviewMemberRelationship query

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 FilmMemberRelationship query

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 IncludeFriends query

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 int32 (number) query

If set, limits the returned log entries to those with date that falls during the specified year.
month int32 (number) query

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 int32 (number) query

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 int32 (number) query

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 number query

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 number query

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 Examples int32 (number) query

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

 
1990
filmYear Examples int32 (number) query

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

 
1994
genre string query

The LID of the genre. If set, limits the returned log entries to those for films that match the specified genre.
includeGenre string[]
(exploded form-style)
query

Specify the LID of up to 100 genres to limit the returned log entries to those for films within all of the specified genres.
excludeGenre string[]
(exploded form-style)
query

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

Specify the ISO 3166-1 defined code of the country to limit films to those produced by the specified country.
language string query

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

Use tagCode instead.
tagCode string query

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

Must be used with tagCode or includeTags. Specify the LID of a member to focus the tag filter on the member.
includeTaggerFriends IncludeFriends query

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.
includeTags string[]
(exploded form-style)
query

Specify a list of tag codes to limit the returned log entries to those with all the specified tags.
excludeTags string[]
(exploded form-style)
query

Specify a list of tag codes to limit the returned log entries to those with none of the specified tags.
service string query

Specify the ID of a supported service to limit films to those available from that service. The list of available services can be found by using the /films/film-services endpoint.
availabilityType string[]
(exploded form-style)
query

Specify the availability types to limit films to those with those availability types. The list of availability types can be found by using the /films/availability-types endpoint.
exclusive boolean query

Set to true to limit films to those available on only one service.
unavailable boolean query

Set to true to limit films to those not available on any services.
includeOwned boolean query

Set to true to include films that the user owns.
negate boolean query

Set to true to invert the current service filtering options.
where Examples LogEntryWhereClause[]
(exploded form-style)
query

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.

 
where=Clean&where=NoSpoilers
filter Examples array of enum ∈ { NoDuplicateMembers }
(exploded form-style)
query

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.

 
filter=NoDuplicateMembers
Response
200

Success

 LogEntriesResponse
404

Film or Member not found

 ErrorResponse

application/json; charset=UTF-8

GET /log-entry/{id}

Get details about a log entry by ID.

Operation ID
getLogEntry
Security
oauth2
Parameters
id Required string path

The LID of the log entry.
Response
200

Success

 LogEntry
404

No log entry matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

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.

Operation ID
getReviewComments
Security
oauth2
Parameters
id Required string path

The LID of the log entry.
cursor string query

The pagination cursor.
perPage int32 (number) query

The number of items to include per page (default is 20, maximum is 100).
sort enum ∈ { Date, DateLatestFirst, Updates } query

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 boolean query

Use this to discover any comments that were deleted.
Response
200

Success

 ReviewCommentsResponse
404

No log entry matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

GET /log-entry/{id}/me

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

Operation ID
myRelationshipToReview
Security
oauth2 user
Parameters
id Required string path

The LID of the log entry.
Response
200

Success

 ReviewRelationship
404

No log entry matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

GET /log-entry/{id}/statistics

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

Operation ID
getReviewStatistics
Security
oauth2
Parameters
id Required string path

The LID of the log entry.
Response
200

Success

 ReviewStatistics
404

No log entry matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

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.

Operation ID
createLogEntry
Security
oauth2 user, content:modify
Request

LogEntryCreationRequest

application/json; charset=UTF-8

Response
200

Success

 LogEntry
400

Bad request

 ErrorResponse
404

The film was not found

 ErrorResponse

application/json; charset=UTF-8

POST /log-entry/{id}/comments

Create a comment on a review.

Operation ID
createReviewComment
Security
oauth2 user, content:modify
Request

CommentCreationRequest

application/json; charset=UTF-8

Parameters
id Required string path

The LID of the log entry.
Response
200

Success

 ReviewComment
400

Bad request

 ErrorResponse
403

The authenticated member is not authorized to comment on this review

 ErrorResponse
404

No film matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

POST /log-entry/{id}/report

Report a log entry’s review by ID.

Operation ID
reportReviewComment
Security
oauth2 user, content:modify
Request

ReportReviewRequest

application/json; charset=UTF-8

Parameters
id Required string path

The LID of the log entry.
Response
204

Success
404

No log entry matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

PATCH /log-entry/{id}

Update a log entry by ID.

Operation ID
updateLogEntry
Security
oauth2 user, content:modify
Request

LogEntryUpdateRequest

application/json; charset=UTF-8

Parameters
id Required string path

The LID of the log entry.
Response
200

Success

 ReviewUpdateResponse
400

Bad request

 ErrorResponse
404

No log entry matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

PATCH /log-entry/{id}/me

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

Operation ID
updateMyRelationshipToReview
Security
oauth2 user
Request

ReviewRelationshipUpdateRequest

application/json; charset=UTF-8

Parameters
id Required string path

The LID of the log entry.
Response
200

Success

 ReviewRelationshipUpdateResponse
403

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

 ErrorResponse
404

No log entry matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

DELETE /log-entry/{id}

Delete a log entry by ID.

Operation ID
deleteLogEntry
Security
oauth2 user, content:modify
Parameters
id Required string path

The LID of the log entry.
Response
204

Success
400

Bad request

 ErrorResponse
403

The authenticated member is not authorized to delete this log entry

 ErrorResponse
404

No log entry matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

Me

GET /me

Get details about the authenticated member.

Operation ID
whoAmI
Security
oauth2 user
Response
200

Success

 MemberAccount

application/json; charset=UTF-8

GET /me/check-tag

Check whether a tag is being merged before update.

Operation ID
checkTag
Security
oauth2 user
Request

TagCheckRequest

application/json; charset=UTF-8

Response
200

Success

 TagCheckResponse
400

Bad request

 ErrorResponse
403

The signed-in user does not have permission to mass-edit tags.

 ErrorResponse

application/json; charset=UTF-8

POST /me/collect-item

Collect a hunt item.

Operation ID
collect
Security
oauth2 user, content:modify
Request

CollectRequest

application/json; charset=UTF-8

Response
200

Success
403

The signed-in user does not have permission to mass-edit tags.

 ErrorResponse

application/json; charset=UTF-8

POST /me/deregister-push-notifications

Deregister a device so it no longer receives push notifications.

Operation ID
deregisterPushNotifications
Security
oauth2 client:firstparty
Request

DeregisterPushNotificationsRequest

application/json; charset=UTF-8

Response
204

Success

POST /me/disable

Deactivate account.

Operation ID
disable
Security
oauth2 user:owner, security:modify
Request

DisableAccountRequest

application/json; charset=UTF-8

Response
204

Success
403

The authenticated member provided incorrect authentication details (password and or two-factor auth code)

 ErrorResponse

application/json; charset=UTF-8

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.

Operation ID
registerPushNotifications
Security
oauth2 user, client:firstparty
Request

RegisterPushNotificationsRequest

application/json; charset=UTF-8

Response
204

Success

POST /me/validation-request

Request a validation link via email.

If the email address associated with a member’s account has not been validated and the validation link has expired or been lost, use this endpoint to request a new validation link.

Operation ID
validationEmailRequest
Security
oauth2 user
Response
204

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

The authenticated member’s email address was already successfully validated

 ErrorResponse
429

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

application/json; charset=UTF-8

PATCH /me

Update the account settings for the authenticated member.

Operation ID
update
Security
oauth2 user:owner, profile:modify
Request

MemberSettingsUpdateRequest

application/json; charset=UTF-8

Response
200

Success

 MemberSettingsUpdateResponse
400

Bad request

 ErrorResponse
403

The request was not allowed

 ErrorResponse

application/json; charset=UTF-8

PATCH /me/update-tag

Update the tag code of a tagging.

Operation ID
updateTag
Security
oauth2 user, content:modify
Request

TagUpdateRequest

application/json; charset=UTF-8

Response
200

Success
403

The signed-in user does not have permission to mass-edit tags.

 ErrorResponse

application/json; charset=UTF-8

DELETE /me/delete-tag

Delete a tag.

Operation ID
deleteTag
Security
oauth2 user, content:modify
Request

TagDeleteRequest

application/json; charset=UTF-8

Response
204

Success
400

Bad request

 ErrorResponse
403

The signed-in user does not have permission to mass-edit tags.

 ErrorResponse

application/json; charset=UTF-8

Members

GET /member/{id}

Get details about a member by ID.

Operation ID
getMemberDetails
Security
oauth2
Parameters
id Required string path

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.

 ErrorResponse

application/json; charset=UTF-8

GET /member/{id}/activity

A cursored window over the activity for a member.

Use the next cursor to move through the list.

Operation ID
activity
Security
oauth2
Parameters
id Required string path

The LID of the member.
cursor string query

The pagination cursor.
perPage int32 (number) query

The number of items to include per page (default is 20, maximum is 100).
include ActivityFilter[]
(exploded form-style)
query

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, and FilmWatchActivity is included.Otherwise all activity except FilmLikeActivity, FilmWatchActivity, FilmRatingActivity and FollowActivity is included.These defaults mimic those shown on the website.
exclude ActivityFilter[]
(exploded form-style)
query

Only supported for paying members.DEPRECATED Use include instead.
where array of enum ∈ { OwnActivity, NotOwnActivity, IncomingActivity, NotIncomingActivity }
(exploded form-style)
query

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 boolean query

Whether to include activity related to adult content. Default to false.
combine boolean query

Whether to group related activity into combined events. Default to false.
parentActivity string query

The parent combined activity for which to retrieve the related child activity. Defaults to null.
Response
200

Success

 ActivityResponse
404

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

 ErrorResponse

application/json; charset=UTF-8

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.

Operation ID
autocompleteListTags
Security
oauth2
Parameters
id Required string path

The LID of the member.
input string query

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.

 ErrorResponse

application/json; charset=UTF-8

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.

Operation ID
autocompleteListTagInfo
Security
oauth2
Parameters
id Required string path

The LID of the member.
input string query

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.

 ErrorResponse

application/json; charset=UTF-8

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.

Operation ID
autocompleteLogEntryTags
Security
oauth2
Parameters
id Required string path

The LID of the member.
input string query

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.

 ErrorResponse

application/json; charset=UTF-8

GET /member/{id}/me

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

Operation ID
relationship
Security
oauth2 user
Parameters
id Required string path

The LID of the other member.
Response
200

Success

 MemberRelationship
404

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

 ErrorResponse

application/json; charset=UTF-8

GET /member/{id}/review-tags

DEPRECATED

Please use /log-entry-tags

Operation ID
autocompleteReviewTags
Security
oauth2
Parameters
id Required string path

The LID of the member.
input string query

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.

 ErrorResponse

application/json; charset=UTF-8

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

DEPRECATED

Please use /log-entry-tags instead

Operation ID
autocompleteReviewTagInfo
Security
oauth2
Parameters
id Required string path

The LID of the member.
input string query

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.

 ErrorResponse

application/json; charset=UTF-8

GET /member/{id}/statistics

Get statistical data about a member by ID.

Operation ID
getMemberStatistics
Security
oauth2
Parameters
id Required string path

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.

 ErrorResponse

application/json; charset=UTF-8

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.

Operation ID
watchlist
Security
oauth2
Parameters
id Required string path

The LID of the member.
cursor string query

The pagination cursor.
perPage int32 (number) query

The number of items to include per page (default is 20, maximum is 100).
filmId Examples string[]
(exploded form-style)
query

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

 
filmId=b8wK&filmId=imdb:tt1396484
genre string query

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

FIRST PARTY Specify the LID of a film to limit films to those similar to the specified film.
theme string query

FIRST PARTY Specify the code of a theme to limit films to those within the specified theme.
minigenre string query

FIRST PARTY Specify the code of a minigenre to limit films to those within the specified minigenre.
nanogenre string query

FIRST PARTY Specify the code of a nanogenre to limit films to those within the specified nanogenre.
includeGenre string[]
(exploded form-style)
query

Specify the LID of up to 100 genres to limit films to those within all of the specified genres.
excludeGenre string[]
(exploded form-style)
query

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

Specify the ISO 3166-1 defined code of the country to limit films to those produced by the specified country.
language string query

Specify the ISO 639-1 defined code of the language to limit films to those using the specified spoken language.
decade Examples int32 (number) query

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

 
1990
year Examples int32 (number) query

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

 
1994
service string query

Specify the ID of a supported service to limit films to those available from that service. The list of available services can be found by using the /films/film-services endpoint.
availabilityType string[]
(exploded form-style)
query

Specify the availability types to limit films to those with those availability types. The list of availability types can be found by using the /films/availability-types endpoint.
exclusive boolean query

Set to true to limit films to those available on only one service.
unavailable boolean query

Set to true to limit films to those not available on any services.
includeOwned boolean query

Set to true to include films that the user owns.
negate boolean query

Set to true to invert the current service filtering options.
where Examples FilmWhereClause[]
(exploded form-style)
query

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

 
where=Watched&where=Released
memberMinRating number query

Allowable values are between 0.5 and 5.0, with increments of 0.5. If set, limits the returned films for the member to those with a rating equal to or higher than the specified rating.
memberMaxRating number query

Allowable values are between 0.5 and 5.0, with increments of 0.5. If set, limits the returned films for the member to those with a rating equal to or lower than the specified rating.
member string query

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 FilmMemberRelationship query

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 IncludeFriends query

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 DEPRECATED string query

Use tagCode instead.
tagCode string query

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

Must be used with tagCode or includeTags. Specify the LID of a member to focus the tag filter on the member.
includeTaggerFriends IncludeFriends query

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.
includeTags string[]
(exploded form-style)
query

Specify a list of tag codes to limit the returned films to those with all the specified tags.
excludeTags string[]
(exploded form-style)
query

Specify a list of tag codes to limit the returned films to those with none of the specified tags.
sort enum ∈ { Added, DateLatestFirst, DateEarliestFirst, Shuffle, FilmName, OwnerRatingHighToLow, OwnerRatingLowToHigh, AuthenticatedMemberRatingHighToLow, AuthenticatedMemberRatingLowToHigh, AuthenticatedMemberBasedOnLiked, AuthenticatedMemberRelatedToLiked, MemberRatingHighToLow, MemberRatingLowToHigh, AverageRatingHighToLow, AverageRatingLowToHigh, ReleaseDateLatestFirst, ReleaseDateEarliestFirst, FilmDurationShortestFirst, FilmDurationLongestFirst, FilmPopularity, RatingHighToLow, RatingLowToHigh, FilmPopularityThisWeek, FilmPopularityThisMonth, FilmPopularityThisYear } query

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

 ErrorResponse
404

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

 ErrorResponse

application/json; charset=UTF-8

GET /members

A cursored window over the list of members.

Use the next cursor to move through the list.

Operation ID
members
Security
oauth2
Parameters
cursor string query

The pagination cursor.
perPage int32 (number) query

The number of items to include per page (default is 20, maximum is 100).
sort enum ∈ { Date, Name, MemberPopularity, MemberPopularityThisWeek, MemberPopularityThisMonth, MemberPopularityThisYear, MemberPopularityWithFriends, MemberPopularityWithFriendsThisWeek, MemberPopularityWithFriendsThisMonth, MemberPopularityWithFriendsThisYear } query

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 string query

Specify the LID of a member to return members who follow or are followed by the member.
memberRelationship enum ∈ { IsFollowing, IsFollowedBy } query

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 string query

Specify the LID of a film to return members who have interacted with the film.
filmRelationship FilmMemberRelationship query

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.
filmMinRating number query

Allowable values are between 0.5 and 5.0, with increments of 0.5. If set, limits the returned members for the film to those with a rating equal to or higher than the specified rating.
filmMaxRating number query

Allowable values are between 0.5 and 5.0, with increments of 0.5. If set, limits the returned members for the film to those with a rating equal to or lower than the specified rating.
list string query

Specify the LID of a story to return members who like the story.
listRelationship ListMemberRelationship query

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 string query

Specify the LID of a review to return members who like the review.
storyRelationship StoryMemberRelationship query

Must be used in conjunction with story. Defaults to Liked, which returns the list of members who have liked the story.
Response
200

Success

 MembersResponse
403

The request was not allowed

 ErrorResponse

application/json; charset=UTF-8

GET /members/pronouns

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

Operation ID
getPronounList
Security
oauth2
Response
200

Success

 PronounsResponse

application/json; charset=UTF-8

POST /member/{id}/report

Report a member by ID.

Operation ID
reportMember
Security
oauth2 user, content:modify
Request

ReportMemberRequest

application/json; charset=UTF-8

Parameters
id Required string path

The LID of the member.
Response
204

Success
404

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

 ErrorResponse

application/json; charset=UTF-8

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.

Operation ID
register
Security
oauth2
Request

RegisterRequest

application/json; charset=UTF-8

Response
201

Success

 Member
400

The username was already taken or is invalid.

 ErrorResponse

application/json; charset=UTF-8

PATCH /member/{id}/me

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

Operation ID
updateRelationship
Security
oauth2 user, content:modify
Request

MemberRelationshipUpdateRequest

application/json; charset=UTF-8

Parameters
id Required string path

The LID of the other member.
Response
200

Success

 MemberRelationshipUpdateResponse
404

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

 ErrorResponse

application/json; charset=UTF-8

News

GET /news

Get recent news from the Letterboxd editors.

Operation ID
recentNews
Security
oauth2
Parameters
cursor string query

The pagination cursor.
perPage int32 (number) query

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

Success

 NewsResponse

application/json; charset=UTF-8

Search

Stories

GET /stories

A cursored window over a list of stories.

Use the next cursor to move through the list.

Operation ID
stories
Security
oauth2
Parameters
cursor string query

The pagination cursor.
perPage int32 (number) query

The number of items to include per page (default is 20, maximum is 100).
sort enum ∈ { WhenUpdatedLatestFirst, WhenUpdatedEarliestFirst, WhenPublishedLatestFirst, WhenPublishedEarliestFirst, WhenCreatedLatestFirst, WhenCreatedEarliestFirst, StoryTitle, PinnedFirst, WhenLiked } query

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

member string query

Specify the LID of a member to return stories from that member’s account.
memberRelationship StoryMemberRelationship query

Must be used in conjunction with member. Defaults to Owner, which returns stories owned by the member. Use Liked to return stories liked by the member.
where array of enum ∈ { Published, NotPublished }
(exploded form-style)
query

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

 ErrorResponse
404

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

 ErrorResponse

application/json; charset=UTF-8

GET /story/{id}

Get details of a story by ID.

Operation ID
getStory
Security
oauth2
Parameters
id Required string path

The LID of the story.
Response
200

Success

 Story
404

No story matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

GET /story/{id}/comments

A cursored window over the comments for a story.

Use the next cursor to move through the comments.

Operation ID
getStoryComments
Security
oauth2
Parameters
id Required string path

The LID of the story.
cursor string query

The pagination cursor.
perPage int32 (number) query

The number of items to include per page (default is 20, maximum is 100).
sort enum ∈ { Date, DateLatestFirst, Updates } query

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 boolean query

Use this to discover any comments that were deleted.
Response
200

Success

 StoryCommentsResponse
404

No log entry matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

GET /story/{id}/me

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

Operation ID
myRelationshipToStory
Security
oauth2 user
Parameters
id Required string path

The LID of the story.
Response
200

Success

 StoryRelationship
404

No story matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

GET /story/{id}/statistics

Get statistical data about a story by ID.

Operation ID
getStoryStatistics
Security
oauth2
Parameters
id Required string path

The LID of the story.
Response
404

No story matches the specified ID

 ErrorResponse
default

Success

 StoryStatistics

application/json; charset=UTF-8

POST /story/{id}/comments

Create a comment on a story.

Operation ID
createStoryComment
Security
oauth2 user, content:modify
Request

CommentCreationRequest

application/json; charset=UTF-8

Parameters
id Required string path

The LID of the story.
Response
200

Success

 ReviewComment
400

Bad request

 ErrorResponse
403

The authenticated member is not authorized to comment on this review

 ErrorResponse
404

No film matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

PATCH /story/{id}

Update a story by ID.

Operation ID
updateStory
Security
oauth2 user, content:modify
Request

StoryUpdateRequest

application/json; charset=UTF-8

Parameters
id Required string path

The LID of the story.
Response
200

Success

 StoryUpdateResponse
400

Bad request

 ErrorResponse
404

No story matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

PATCH /story/{id}/me

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

Operation ID
updateMyRelationshipToStory
Security
oauth2 user, content:modify
Request

StoryRelationshipUpdateRequest

application/json; charset=UTF-8

Parameters
id Required string path

The LID of the story.
Response
200

Success

 StoryRelationshipUpdateResponse
404

No story matches the specified ID

 ErrorResponse

application/json; charset=UTF-8

Schemas

AbstractActivity

Properties

member Required MemberSummary

The member associated with the activity.
whenCreated Required date-time (string)

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

Discriminator

Name Type
type ActivityType

The type of activity.
Values
Value Reference
CombinedIncomingActivity CombinedIncomingActivity
CombinedPersonActivity CombinedPersonActivity
DiaryEntryActivity DiaryEntryActivity
FilmLikeActivity FilmLikeActivity
FilmRatingActivity FilmRatingActivity
FilmWatchActivity FilmWatchActivity
FollowActivity FollowActivity
ListActivity ListActivity
ListCommentActivity ListCommentActivity
ListLikeActivity ListLikeActivity
ReviewActivity ReviewActivity
ReviewCommentActivity ReviewCommentActivity
ReviewLikeActivity ReviewLikeActivity
ReviewResponseActivity ReviewResponseActivity
StoryActivity StoryActivity
StoryCommentActivity StoryCommentActivity
StoryLikeActivity StoryLikeActivity
WatchlistActivity WatchlistActivity

AbstractComment

Properties

id Required string

The LID of the comment/​reply.
member Required MemberSummary

The member who posted the comment.
whenCreated Required date-time (string)

ISO 8601 format with UTC timezone, i.e. YYYY-MM-DDThh:mm:ssZ
whenUpdated Required date-time (string)

ISO 8601 format with UTC timezone, i.e. YYYY-MM-DDThh:mm:ssZ
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 Required boolean

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

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

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

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

If the content owner has blocked the commenter, blockedByOwner will be true and comment will not be included.
editableWindowExpiresIn DEPRECATED int64 (number)

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.
whenEditingWindowExpires date-time (string)

If the authenticated member posted this comment, and the comment is still editable, this value shows when the editing window closes. ISO 8601 format with UTC timezone, i.e. YYYY-MM-DDThh:mm:ssZ
comment string

The message portion of the comment formatted as HTML.

Discriminator

Name Type
type CommentType

The type of comment.
Values
Value Reference
ListComment ListComment
ReviewComment ReviewComment
StoryComment StoryComment

AbstractSearchItem

Properties

score Required number

A relevancy value that can be used to order results.

Discriminator

Name Type
type SearchResultType

The type of the search result.
Values
Value Reference
ArticleSearchItem ArticleSearchItem
ContributorSearchItem ContributorSearchItem
FilmSearchItem FilmSearchItem
ListSearchItem ListSearchItem
MemberSearchItem MemberSearchItem
PodcastSearchItem PodcastSearchItem
ReviewSearchItem ReviewSearchItem
StorySearchItem StorySearchItem
TagSearchItem TagSearchItem

AccountStatus ENUM

Values

  • Active
  • Memorialized

ActivityFilter ENUM

Values

  • ReviewActivity
  • ReviewCommentActivity
  • ReviewLikeActivity
  • ReviewResponseActivity
  • ListActivity
  • ListCommentActivity
  • ListLikeActivity
  • StoryActivity
  • StoryCommentActivity
  • StoryLikeActivity
  • DiaryEntryActivity
  • FilmRatingActivity
  • FilmWatchActivity
  • FilmLikeActivity
  • WatchlistActivity
  • FollowActivity
  • CombinedPersonActivity
  • CombinedIncomingActivity

ActivityResponse

Properties

next string

The cursor to the next page of results.
items Required AbstractActivity[]

The list of activity items.
itemCount int32 (number)

ActivityType ENUM

Values

  • CombinedPersonActivity
  • CombinedIncomingActivity
  • DiaryEntryActivity
  • FilmLikeActivity
  • FilmRatingActivity
  • FilmWatchActivity
  • FollowActivity
  • ListActivity
  • ListCommentActivity
  • ListLikeActivity
  • ReviewActivity
  • ReviewCommentActivity
  • ReviewLikeActivity
  • ReviewResponseActivity
  • StoryActivity
  • StoryCommentActivity
  • StoryLikeActivity
  • WatchlistActivity

AGoogleBillingSubscription

Properties

subscriptionDaysRemaining int32 (number)

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 Required ListIdentifier

The list.
additions Required int32 (number)

The number of films added to the list.

AListTopic

Properties

name Required string

The topic name.
items Required ListSummary[]

The list of featured lists for the topic.

AppleIAPSubscription

Properties

subscriptionDaysRemaining int32 (number)

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 Required enum ∈ { Error, Success }

The type of message.
code Required enum ∈ { SubscriptionAlreadyExpired, SubscriptionBelongsToAnotherMember, UnexpectedError }

The error message code.
title Required 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

All of

AbstractSearchItem

Properties
article NewsItem

The article.

AvailabilityType

Properties

key Required string

The key value of the availability type.
label Required string

The display name of the availability type.

AvailabilityTypesResponse

Properties

items AvailabilityType[]

The list of availability types.

CollectRequest

Properties

nonce string
token string
itemId string

CombinedIncomingActivity

All of

AbstractActivity

Properties
id string
reviewLikes int32 (number)

The number of review likes grouped under this combined activity
listLikes int32 (number)

The number of film list likes grouped under this combined activity
storyLikes int32 (number)

The number of story likes grouped under this combined activity
reviewComments int32 (number)

The number of review comments grouped under this combined activity
listComments int32 (number)

The number of film list comments grouped under this combined activity
storyComments int32 (number)

The number of story comments grouped under this combined activity
follows int32 (number)

The number of follow actions grouped under this combined activity

CombinedPersonActivity

All of

AbstractActivity

Properties
id string
reviewLikes int32 (number)

The number of review likes grouped under this combined activity
listLikes int32 (number)

The number of film list likes grouped under this combined activity
storyLikes int32 (number)

The number of story likes grouped under this combined activity
reviewComments int32 (number)

The number of review comments grouped under this combined activity
listComments int32 (number)

The number of film list comments grouped under this combined activity
storyComments int32 (number)

The number of story comments grouped under this combined activity
follows int32 (number)

The number of follow actions grouped under this combined activity
filmLikes int32 (number)

The number of film likes grouped under this combined activity
filmRatings int32 (number)

The number of film ratings grouped under this combined activity
filmWatches int32 (number)

The number of film watches grouped under this combined activity
filmsWatchlisted int32 (number)

The number of films watchlisted grouped under this combined activity

CommentCreationRequest

Properties

comment Required string

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

CommentPolicy ENUM

Values

  • Anyone
  • Friends
  • You

CommentSubscriptionState ENUM

Values

  • Subscribed
  • NotSubscribed
  • Unsubscribed

CommentThreadState ENUM

Values

  • Banned
  • Blocked
  • BlockedThem
  • CanComment
  • Closed
  • FriendsOnly
  • Moderated
  • NotCommentable
  • NotValidated

CommentType ENUM

Values

  • ListComment
  • ReviewComment
  • StoryComment

CommentUpdateMessage

Properties

type Required enum ∈ { Error, Success }

The type of message.
code Required enum ∈ { MissingComment, CommentOnContentYouBlocked, CommentOnBlockedContent, CommentBan, CommentEditWindowExpired, CommentTooLong }

The error message code.
title Required string

The error message text in human-readable form.

CommentUpdateRequest

Properties

comment Required string

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

CommentUpdateResponse

Properties

data Required AbstractComment

The response object.
messages Required CommentUpdateMessage[]

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

ContributionStatistics

Properties

type Required ContributionType

The type of contribution.
filmCount Required int32 (number)

The number of films for this contribution type.

ContributionType ENUM

Values

  • Director
  • CoDirector
  • Actor
  • Producer
  • Writer
  • OriginalWriter
  • Story
  • Casting
  • Editor
  • Cinematography
  • AssistantDirector
  • AdditionalDirecting
  • ExecutiveProducer
  • Lighting
  • CameraOperator
  • AdditionalPhotography
  • ProductionDesign
  • ArtDirection
  • SetDecoration
  • SpecialEffects
  • VisualEffects
  • TitleDesign
  • Stunts
  • Choreography
  • Composer
  • Songs
  • Sound
  • Costumes
  • MakeUp
  • Hairstyling
  • Studio

Contributor

Properties

id Required string

The LID of the contributor.
name Required string

The name of the contributor.
tmdbid string

The ID of the contributor on TMDB, if known
bio string

The biography of the contributor on TMDB, if known
customPoster Image

The custom poster for this contributor, if there is one for the currently logged in user (16:9 ratio in multiple sizes).
statistics Required ContributorStatistics

An array of the types of contributions made, with a count of films for each contribution type.
links Required Link[]

A list of relevant URLs for this entity, on Letterboxd and external sites.
huntItems TreasureHuntItem[]

FIRST PARTY The treasure hunt items related to the contributor.

ContributorSearchItem

All of

AbstractSearchItem

Properties
contributor Contributor

Details of the contributor.

ContributorStatistics

Properties

contributions Required ContributionStatistics[]

The statistics for each contribution type.

ContributorSummary

Properties

id Required string

The LID of the contributor.
name Required 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
customPoster Image

The custom poster for this contributor, if there is one for the currently logged in user (16:9 ratio in multiple sizes).

CountriesResponse

Properties

items Country[]

The list of countries.

Country

Properties

code Required string

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

The name of the country.
flagUrl url (string)

The URL of the SVG image representing the country’s flag.

DeregisterPushNotificationsRequest

Properties

deviceId Required string

The device ID.

DiaryDetails

Properties

diaryDate Required date (string)

The date the film was watched, if specified, in ISO 8601 format, i.e. YYYY-MM-DD
rewatch Required 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

All of

AbstractActivity

Properties
diaryEntry LogEntry

The log entry associated with this activity

DisableAccountRequest

Properties

currentPassword Required string

The member’s current password.
authenticationCode string

The member’s current two-factor authentication code. Only required for members that have two-factor authentication enabled.
mode enum ∈ { Disable, Delete }

The disable account mode - defaults to 'Disable' if not specified.

ErrorResponse

Properties

error Required boolean
message Required string
code string

Film

Properties

id Required string

The LID of the film.
name Required string

The title of the film.
originalName string

FIRST PARTY The original title of the film, if it was first released with a non-English title.
sortingName Required string

A modified version of the name that has been normalized for consistent sorting.
alternativeNames string[]

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

The year in which the film was first released.
runTime int32 (number)

The film’s duration (in minutes).
rating number

The weighted average rating of the film between 0.5 and 5.0. Only available for films that have received sufficient ratings.
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 int32 (number)

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 Required boolean

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

true if reviews for the film are hidden due to a high volume of moderation traffic.
posterCustomisable Required boolean

true if the poster for this film can be customised by any member.
filmCollectionId string

The LID of the collection containing this film.
links Required 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 Required Genre[]

The film’s genres.
tagline string

The tagline for the film.
description string

A synopsis of the film.
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[]

FIRST PARTY The film’s production countries.
originalLanguage DEPRECATED Language

The film’s original language.
productionLanguage Language

FIRST PARTY The film’s original production language.
primaryLanguage Language

The film’s primary spoken language.
languages Language[]

FIRST PARTY The film’s spoken languages.
releases Release[]

FIRST PARTY The film’s release information.
contributions Required 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.
huntItems TreasureHuntItem[]

FIRST PARTY The treasure hunt items related to the film.
targeting string[]

FIRST PARTY The ad targeting values.

FilmAvailability

Properties

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

Use displayName instead.
displayName Required string

The name of the service.
icon url (string)

The URL of the thumbnail image for the service.
country Required 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, AGO, COD, CMR, CUB, GUY, MDG, MKD, MLI, MNE, MWI, PSE, TCD }

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 Required url (string)

The URL for the film on this service.
types Required array of enum ∈ { rent, cinema, buy, stream }

The types of the availability.
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 Required string

The LID of the film collection.
name Required string

The name of the collection.
films Required FilmSummary[]

The list of films in the collection.
links Required Link[]

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

FilmContribution

Properties

type Required ContributionType

The type of contribution.
film Required FilmSummary

The film.
characterName string

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

Will be true if the contribution contains plot spoilers for the film.

FilmContributions

Properties

type Required ContributionType

The type of contribution.
contributors Required ContributorSummary[]

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

FilmContributionsResponse

Properties

next string

The cursor to the next page of results.
items Required FilmContribution[]

The list of contributions.
itemCount int32 (number)
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 Required ContributionType

The type of contribution.
data Required FilmsMetadata

The details for this contribution type.

FilmContributorRelationship

Properties

type Required ContributionType

The type of contribution.
relationship Required FilmsRelationship

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

FilmIdentifier

Properties

id Required string

The LID of the film.

FilmLikeActivity

All of

AbstractActivity

Properties
film FilmSummary

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

FilmMemberRelationship ENUM

Values

  • Ignore
  • Watched
  • NotWatched
  • Liked
  • NotLiked
  • Rated
  • NotRated
  • InWatchlist
  • NotInWatchlist
  • Favorited

FilmRatingActivity

All of

AbstractActivity

Properties
film FilmSummary

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

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

FilmRelationship

Properties

watched Required boolean

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

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

Will be true if the member likes the film (via the ‘heart’ icon).
whenLiked date-time (string)

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

Will be true if the member has the film as one of their four favorites.
owned boolean

Will be true if the member owns the film. Only returned for paying members.
inWatchlist Required boolean

Will be true if the film is in the member’s watchlist.
whenAddedToWatchlist date-time (string)

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

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

The member’s rating for the film.
reviews Required string[]

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

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

FilmRelationshipUpdateMessage

Properties

type Required enum ∈ { Error, Success }

The type of message.
code Required enum ∈ { InvalidRatingValue, UnableToRemoveWatch }

The error message code.
title Required string

The error message text in human-readable form.

FilmRelationshipUpdateRequest

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

Properties

watched boolean

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

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

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

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

FilmRelationshipUpdateResponse

Properties

data Required FilmRelationship

The response object.
messages Required FilmRelationshipUpdateMessage[]

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

FilmsAutocompleteResponse

Properties

items Required FilmSummary[]

The list of films.
itemCount int32 (number)

FilmSearchItem

All of

AbstractSearchItem

Properties
film FilmSummary

The film returned by the search.

FilmServicesResponse

Properties

items Service[]

The list of film services.

FilmsMemberRelationship

Properties

member Required MemberSummary

The member.
relationship Required FilmsRelationship

The relationship details.

FilmsMetadata

Properties

totalFilmCount Required int32 (number)

The total number of films.
filteredFilmCount Required int32 (number)

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

FilmsRelationship

Properties

counts Required FilmsRelationshipCounts

The number of watches and likes for the films.

FilmsRelationshipCounts

Properties

watches Required int32 (number)

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

The number of films the member has indicated they liked.

FilmsResponse

Properties

next string

The cursor to the next page of results.
items Required FilmSummary[]

The list of films.
itemCount int32 (number)

FilmStatistics

Properties

film Required FilmIdentifier

The film for which statistics were requested.
counts Required FilmStatisticsCounts

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

The weighted average rating of the film between 0.5 and 5.0. Only available for films that have received sufficient ratings.
ratingsHistogram RatingsHistogramBar[]

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

FilmStatisticsCounts

Properties

watches Required int32 (number)

The number of members who have watched the film.
likes Required int32 (number)

The number of members who have liked the film.
ratings Required int32 (number)

The number of members who have rated the film.
fans Required int32 (number)

The number of members who have the film as one of their four favorites.
lists Required int32 (number)

The number of lists in which the film appears.
reviews Required int32 (number)

The number of reviews for the film.

FilmSummary

Properties

id Required string

The LID of the film.
name Required string

The title of the film.
originalName string

FIRST PARTY The original title of the film, if it was first released with a non-English title.
sortingName Required string

A modified version of the name that has been normalized for consistent sorting.
alternativeNames string[]

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

The year in which the film was first released.
runTime int32 (number)

The film’s duration (in minutes).
rating number

The weighted average rating of the film between 0.5 and 5.0. Only available for films that have received sufficient ratings.
directors Required 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 int32 (number)

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 Required boolean

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

true if reviews for the film are hidden due to a high volume of moderation traffic.
posterCustomisable Required boolean

true if the poster for this film can be customised by any member.
filmCollectionId string

The LID of the collection containing this film.
links Required 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 Required Genre[]

The film’s genres.

FilmTrailer

Properties

id Required string

The YouTube ID of the trailer.
url Required url (string)

The YouTube URL for the trailer.

FilmWatchActivity

All of

AbstractActivity

Properties
film FilmSummary

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

FilmWhereClause ENUM

Values

  • 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

FollowActivity

All of

AbstractActivity

Properties
followed MemberSummary

A summary of the member that was followed.

ForgottenPasswordRequest

Properties

emailAddress string

FriendFilmRelationshipsResponse

Properties

next string

The cursor to the next page of results.
items Required MemberFilmViewingRelationship[]

The list of film relationships for members.
itemCount int32 (number)
watchCount Required int32 (number)

The number of friends who have watched the film
watchListCount Required int32 (number)

The number of friends who want to watch the film

Genre

Properties

id Required string

The LID of the genre.
name Required string

The name of the genre.

GenresResponse

Properties

items Genre[]

The list of genres.

GoogleBillingSubscriptionMessage

Properties

type Required enum ∈ { Error, Success }

The type of message.
code Required enum ∈ { SubscriptionAlreadyExpired, SubscriptionBelongsToAnotherMember, UnexpectedError }

The error message code.
title Required string

The error message text in human-readable form.

GoogleBillingSubscriptionRequest

Properties

packageName Required string

The package name.
subscriptionId Required string

The subscription ID.
purchaseToken Required string

The purchase token.

GoogleBillingSubscriptionResponse

Properties

data Required AGoogleBillingSubscription

The response object.
messages Required GoogleBillingSubscriptionMessage[]

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

Image

Properties

sizes Required ImageSize[]

The available sizes for the image.

ImageSize

Properties

width Required int32 (number)

The image width in pixels.
height Required int32 (number)

The image height in pixels.
url Required url (string)

The URL to the image file.

IncludeFriends ENUM

Values

  • None
  • All
  • Only

Language

Properties

code Required string

The ISO 639-1 defined code of the language.
name Required string

The name of the language.

LanguagesResponse

Properties

items Language[]

The list of languages.

Link

Properties

type Required enum ∈ { letterboxd, boxd, tmdb, imdb, justwatch, facebook, instagram, twitter, youtube, tickets, tiktok }

Denotes which site the link is for.
id Required string

The object ID for the linked entity on the destination site.
url Required url (string)

The fully qualified URL on the destination site.
label string

The optional label for the link, may be empty or missing.
checkUrl string

The optional check url.

List

Properties

id Required string

The LID of the list.
name Required string

The name of the list.
version int64 (number)

The list version, used to avoid editing collisions.
filmCount Required int32 (number)

The number of films in the list.
published Required boolean

Will be true if the owner has elected to publish the list for other members to see.
ranked Required boolean

Will be true if the owner has elected to make this a ranked list.
hasEntriesWithNotes Required boolean

Will be true if the owner has added notes to any entries.
descriptionLbml string

The list description in LBML. May contain the following HTML tags: <br> <strong> <em> <b> <i> <a href=""> <blockquote>.
tags string[]

Use tags2 instead.
tags2 Required Tag[]

The tags for the list.
whenCreated Required date-time (string)

ISO 8601 format with UTC timezone, i.e. YYYY-MM-DDThh:mm:ssZ
whenPublished date-time (string)

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

The policy determining who can post comments to the list. You in this context refers to the content owner. Use the commentThreadState property of the ListRelationship to determine the signed-in member’s ability to comment (or not).
sharePolicy Required SharePolicy

The policy determining who has access to the list.

owner Required MemberSummary

The member who created the list.
clonedFrom ListIdentifier

The list this was cloned from, if applicable.
previewEntries Required ListEntrySummary[]

The first 12 entries in the list. To fetch more than 12 entries, and to fetch the entry notes, use the /list/{id}/entries endpoint.
links Required Link[]

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

The list’s backdrop image at multiple sizes, sourced from the first film in the list, if available. Only returned for Patron members.
backdropFocalPoint number

The vertical focal point of the list’s backdrop image, if available. 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.
description string

The list description formatted as HTML.

ListActivity

All of

AbstractActivity

Properties
list ListSummary

The list associated with the activity.
clonedFrom ListSummary

The list that was cloned, if applicable

ListAdditionRequest

Properties

lists string[]

Specify the LIDs of lists to be added to.
films string[]

Specify the LIDs of films to be added to each of the specified lists.

ListAdditionResponse

Properties

items Required AListAddition[]

The list of additions to each list.

ListComment

All of

AbstractComment

Properties
blockedByOwner boolean

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

The list on which the comment was posted.

ListCommentActivity

All of

AbstractActivity

Properties
list ListSummary

The list associated with the activity.
comment ListComment

The comment associated with the activity.

ListCommentsResponse

Properties

next string

The cursor to the next page of results.
items Required ListComment[]

The list of comments.
itemCount int32 (number)

ListCreateMessage

Properties

type Required enum ∈ { Error, Success }

The type of message.
code Required enum ∈ { ListNameTooLong, ListNameIsBlank, UnknownFilmCode, InvalidRatingValue, DuplicateRank, EmptyPublicList, CloneSourceNotFound, SharingServiceNotAuthorized, CannotSharePrivateList, ListDescriptionIsTooLong, ListEntryNotesTooLong }

The error message code.
title Required string

The error message text in human-readable form.

ListCreateResponse

Properties

data Required List

The response object.
messages Required ListCreateMessage[]

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

ListCreationRequest

Properties

published Required boolean

Set to true if the owner has elected to publish the list for other members to see.
name Required string

The name of the list.
commentPolicy CommentPolicy

The policy determining who can post comments to the list. You in this context refers to the content owner. Use the commentThreadState property of the ListRelationship to determine the signed-in member’s ability to comment (or not).
sharePolicy SharePolicy

The policy determining who has access to the list.

ranked Required boolean

Set to true if the owner has elected to make this a ranked list.
description string

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

The LID of a list to clone from. This property is deprecated, use clonedList instead. Only supported for paying members.
clonedList string

The LID of a list to clone entries from. Only supported for paying members.
tags string[]

The tags for the list.
entries ListUpdateEntryForm[]

The update actions used to build the list. If clonedList is set the entries from that list are first added and then these updates are applied.

ListEntriesResponse

Properties

next string

The cursor to the next page of results.
items Required ListEntry[]

The list of entries.
itemCount int32 (number)
metadata Required FilmsMetadata

The filtered and total count of films in the list.
relationships Required FilmsMemberRelationship[]

The relationships to the films in the list for the members referenced in the request.

ListEntry

Properties

rank int32 (number)

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

A unique ID for this entry in the list.
notesLbml string

The notes for the list entry in LBML. May contain the following HTML tags: <br> <strong> <em> <b> <i> <a href=""> <blockquote>.
posterPickerUrl string

FIRST PARTY The custom poster picker URL.
containsSpoilers boolean

Will be true if the member has indicated that the notes field contains plot spoilers for the film.
film Required FilmSummary

The film for this entry. Includes a MemberFilmRelationship for the member who created the list.
notes string

The notes for the list entry formatted as HTML.

ListEntryOccurrence

Properties

rank Required int32 (number)

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

The film LID for this entry.

ListEntrySummary

Properties

rank int32 (number)

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

The film for this entry.

ListIdentifier

Properties

id Required string

The LID of the list.

ListLikeActivity

All of

AbstractActivity

Properties
list ListSummary

The list associated with the activity.

ListMemberRelationship ENUM

Values

  • Owner
  • Liked
  • Accessed

ListRelationship

Properties

liked Required boolean

Will be true if the member likes the list (via the ‘heart’ icon). A member may not like their own list.
subscribed Required boolean

Will be true if the member is subscribed to comment notifications for the list
subscriptionState Required CommentSubscriptionState

Defaults to Subscribed for the list’s owner, and NotSubscribed for other members. The subscription value may change when a member (other than the owner) posts a comment, as follows: the member will become automatically Subscribed unless they have previously Unsubscribed from the comment thread via the web interface or API, or unless they have disabled comment notifications in their account settings. NotSubscribed and Unsubscribed are maintained as separate states so the UI can, if needed, indicate to the member how their subscription state will be affected if/when they post a comment.
commentThreadState Required CommentThreadState

The authenticated member’s state with respect to posting comments to the list.Banned means the Letterboxd community managers have restricted the member’s ability to post comments.Blocked means the owner has blocked the member from posting comments.BlockedThem means the member has blocked the owner and is therefore unable to post comments.CanComment means the authenticated member is authorized to post a comment (also known as a “reply”). All other values mean the authenticated member is not authorized to post a comment.Closed means the owner has closed the comment thread to all other members.FriendsOnly means the owner is only accepting comments from members they follow.Moderated means the Letterboxd community managers have removed the content (applies to reviews only).NotCommentable means that comments may not be posted to this thread.NotValidated means the owner has not validated their email address.

ListRelationshipUpdateMessage

Properties

type Required enum ∈ { Error, Success }

The type of message.
code Required enum ∈ { LikeBlockedContent, LikeOwnList, LikeRateLimit, SubscribeWhenOptedOut, SubscribeToContentYouBlocked, SubscribeToBlockedContent }

The error message code.
title Required string

The error message text in human-readable form.

ListRelationshipUpdateRequest

Properties

liked boolean | null

Set to true if the member likes the list (via the ‘heart’ icon). A member may not like their own list.
subscribed boolean | null

Set to true to subscribe the member to comment notifications for the list, or false to unsubscribe them. A value of true will be ignored if the member has disabled comment notifications in their account settings.

ListRelationshipUpdateResponse

Properties

data Required ListRelationship

The response object.
messages Required ListRelationshipUpdateMessage[]

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

ListSearchItem

All of

AbstractSearchItem

Properties
list ListSummary

The list.

ListsResponse

Properties

next string

The cursor to the next page of results.
items Required ListSummary[]

The list of lists.
itemCount int32 (number)

ListStatistics

Properties

list Required ListIdentifier

The list for which statistics were requested.
counts Required ListStatisticsCounts

The number of comments and likes for the list.

ListStatisticsCounts

Properties

comments Required int32 (number)

The number of comments for the list.
likes Required int32 (number)

The number of members who like the list.

ListSummary

Properties

id Required string

The LID of the list.
name Required string

The name of the list.
version int64 (number)

The list version, used to avoid editing collisions.
filmCount Required int32 (number)

The number of films in the list.
published Required boolean

Will be true if the owner has elected to publish the list for other members to see.
ranked Required boolean

Will be true if the owner has elected to make this a ranked list.
descriptionLbml string

The list description in LBML. May contain the following HTML tags: <br> <strong> <em> <b> <i> <a href=""> <blockquote>. The text is a preview extract, and may be truncated if it’s too long.
descriptionTruncated boolean

Will be true if the list description was truncated because it’s very long.
sharePolicy Required SharePolicy

The policy determining who has access to the list.

owner Required MemberSummary

The member who created the list.
clonedFrom ListIdentifier

The list this was cloned from, if applicable.
previewEntries Required ListEntrySummary[]

The first 12 entries in the list. To fetch more than 12 entries, and to fetch the entry notes, use the /list/{id}/entries endpoint.
entriesOfNote ListEntryOccurrence[]

Returned when one or more filmsOfNote is specified in the request. Contains, for each list in the response, the rank position of each film of note (if in the list) or -1 (if not).
description string

The list description formatted as HTML. The text is a preview extract, and may be truncated if it’s too long.

ListUpdateEntry

Properties

film string

The LID of the film. Required for ADD actions.
rank DEPRECATED int32 (number)

If the list is ranked, this is the entry’s rank in the list, numbered from 1. If not set, the entry will stay in the same place (if already in the list) or be appended to the end of the list (if not in the list). If set, any entries at or after this position will be incremented by one. Sending two or more ListUpdateEntrys with the same rank will return an error. This property has been deprecated in favour of newPosition. Note that rank is numbered from 1 whereas newPosition is numbered from 0.
notes string

The notes for the list entry in LBML. May contain the following HTML tags: <br> <strong> <em> <b> <i> <a href=""> <blockquote>. This field has a maximum size of 100,000 characters.
containsSpoilers boolean

Set to true if the member has indicated that the notes field contains plot spoilers for the film.
action enum ∈ { ADD, DELETE, UPDATE, CLEAR, SORT_NAME, SORT_DIARY_NEWEST, SORT_DIARY_OLDEST, SORT_RELEASE_NEWEST, SORT_RELEASE_OLDEST, SORT_RATING_HIGHEST, SORT_RATING_LOWEST, SORT_AVR_RATING_HIGHEST, SORT_AVR_RATING_LOWEST, SORT_LENGTH_SHORTEST, SORT_LENGTH_LONGEST }

The update action to take. If not set then any existing entry for the film will be updated, if there is no existing entry for the film it will be added into the list.
position int32 (number)

The entry position (numbered from 0) to update or delete. Required for UPDATE and DELETE actions.
newPosition int32 (number)

The new entry position (numbered from 0) for the updated or added entry. If not set, the entry will stay in the same place (for UPDATE actions) or be appended to the end of the list (for ADD actions).

ListUpdateEntryForm

Properties

film string
rank int32 (number)
notes string
containsSpoilers boolean
action enum ∈ { ADD, DELETE, UPDATE, CLEAR, SORT_NAME, SORT_DIARY_NEWEST, SORT_DIARY_OLDEST, SORT_RELEASE_NEWEST, SORT_RELEASE_OLDEST, SORT_RATING_HIGHEST, SORT_RATING_LOWEST, SORT_AVR_RATING_HIGHEST, SORT_AVR_RATING_LOWEST, SORT_LENGTH_SHORTEST, SORT_LENGTH_LONGEST }
position int32 (number)
newPosition int32 (number)

ListUpdateMessage

Properties

type Required enum ∈ { Error, Success }

The type of message.
code Required enum ∈ { ListNameTooLong, ListModerated, ListNameIsBlank, ListVersionMismatch, UnknownFilmCode, MissingEntry, InvalidRatingValue, DuplicateRank, InvalidEntry, DuplicateEntry, EmptyPublicList, SharingServiceNotAuthorized, CannotSharePrivateList, ListDescriptionIsTooLong, ListEntryNotesTooLong }

The error message code.
title Required string

The error message text in human-readable form.

ListUpdateRequest

Properties

version int64 (number)

The list version, used to avoid editing collisions.
published boolean

Set to true if the owner has elected to publish the list for other members to see.
name string

The name of the list.
commentPolicy CommentPolicy

The policy determining who can post comments to the list. You in this context refers to the content owner. Use the commentThreadState property of the ListRelationship to determine the signed-in member’s ability to comment (or not).
sharePolicy SharePolicy

The policy determining who has access to the list.

ranked boolean

Set to true if the owner has elected to make this a ranked list.
description string

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

The tags for the list.
filmsToRemove string[]

Specify the LIDs of films to be removed from the list.
entries ListUpdateEntry[]

The specified entries will be inserted/​appended to the list if they are not already present, or updated if they are present.

ListUpdateResponse

Properties

data Required List

The response object.
messages Required ListUpdateMessage[]

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

ListWhereClause ENUM

Values

  • Clean
  • Published
  • NotPublished
  • NotPublishedOrShared
  • SharedAnyone
  • SharedFriends
  • Owned
  • Customized

LogEntriesResponse

Properties

next string

The cursor to the next page of results.
items Required LogEntry[]

The list of log entries.
itemCount int32 (number)

LogEntry

Properties

id Required string

The LID of the log entry.
name Required string

A descriptive title for the log entry.
owner Required MemberSummary

The member who created the log entry.
film Required FilmSummary

The film being logged. Includes a MemberFilmRelationship for the member who created the log entry.
diaryDetails DiaryDetails

Details about the log entry, if present.
review Review

Review details for the log entry, if present.
tags DEPRECATED string[]

Use tags2 instead.
tags2 Required Tag[]

The tags for the log entry.
whenCreated Required date-time (string)

The timestamp of when the log entry was created, in ISO 8601 format with UTC timezone, i.e. YYYY-MM-DDThh:mm:ssZ
whenUpdated Required date-time (string)

The timestamp of when the log entry was last updated, in ISO 8601 format with UTC timezone, i.e. YYYY-MM-DDThh:mm:ssZ
rating number

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

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

Will be true if comments can be posted to the log entry by the member. This is determined according to the existence of review text and other factors such as the content owner’s comment policy.
commentPolicy CommentPolicy

The policy determining who can post comments to the log entry. You in this context refers to the content owner. Use the commentThreadState property of the ListRelationship to determine the signed-in member’s ability to comment (or not).
links Required Link[]

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

FIRST PARTY The custom poster picker URL.
backdrop Image

The log entry's backdrop image at multiple sizes, sourced from the film being logged, if available. Only returned for Patron members.
backdropFocalPoint number

The vertical focal point of the log entry’s backdrop image, if available. 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.
targeting string[]

FIRST PARTY The ad targeting values.

LogEntryCreationRequest

Properties

filmId Required string

The film being logged.
diaryDetails LogEntryCreationRequestDiaryDetails

Information about this log entry if adding to the member’s diary.
review LogEntryCreationRequestReview

Information about the review if adding a review.
tags string[]

The tags for the log entry.
rating number

Allowable values are between 0.5 and 5.0, with increments of 0.5.
like boolean

Set to true if the member likes the review (via the ‘heart’ icon). A member may not like their own review.
commentPolicy CommentPolicy

The policy determining who can post comments to the log entry. You in this context refers to the content owner. Use the commentThreadState property of the ListRelationship to determine the signed-in member’s ability to comment (or not).

LogEntryCreationRequestDiaryDetails

Properties

diaryDate Required date (string)

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

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

LogEntryCreationRequestReview

Properties

text Required string

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

Set to true if the member has indicated that the review field contains plot spoilers for the film.

LogEntrySummary

Properties

id Required string

The LID of the log entry.
review Required boolean

Does this log entry contain a review.
diaryEntry Required boolean

Does this log entry specify a diary entry.
rating number

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

LogEntryUpdateMessage

Properties

type Required enum ∈ { Error, Success }

The type of message.
code Required enum ∈ { InvalidRatingValue, InvalidDiaryDate, ReviewWithNoText, ReviewIsTooLong, LogEntryWithNoReviewOrDiaryDetails }

The error message code.
title Required string

The error message text in human-readable form.

LogEntryUpdateRequest

Properties

diaryDetails LogEntryUpdateRequest.DiaryDetails | null

Information about this log entry if adding to the member’s diary. Set to null to remove this log entry from the diary.
review LogEntryUpdateRequest.Review | null

Information about the review. Set to null to remove the review from this log entry.
tags string[] | null

The tags for the log entry.
rating number | null

Accepts values between 0.5 and 5.0, with increments of 0.5, or null (to remove the rating).
like boolean | null

Set to true if the member likes the review (via the ‘heart’ icon). A member may not like their own review.
commentPolicy CommentPolicy | null

The policy determining who can post comments to the log entry. You in this context refers to the content owner. Use the commentThreadState property of the ListRelationship to determine the signed-in member’s ability to comment (or not).

LogEntryWhereClause ENUM

Values

  • 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

LoginTokenResponse

Properties

token Required string

A single-use token for signing into the Letterboxd website.

Member

Properties

id Required string

The LID of the member.
username Required string

The member’s Letterboxd username. Usernames must be between 2 and 15 characters long and may only contain upper or lowercase letters, numbers or the underscore (_) character.
givenName string

The given name of the member.
familyName string

The family name of the member.
displayName Required string

A convenience method that returns the member’s given name and family name concatenated with a space, if both are set, or just their given name or family name, if one is set, or their username, if neither is set. Will never be empty.
shortName Required string

A convenience method that returns the member’s given name, if set, or their username. Will never be empty.
pronoun Pronoun

The member’s preferred pronoun. Use the /members/pronouns endpoint to request all available pronouns.
avatar Image

The member’s avatar image at multiple sizes. Avatar images to not have an enforced aspect ratio, so should be center-cropped to a square if they are not 1:1.
memberStatus Required MemberStatus

The member’s account type.
hideAdsInContent Required boolean

true if ads should not be shown on the member's content.
commentPolicy DEPRECATED CommentPolicy

The member’s default policy determing who can post comments to their content. Supported options are Anyone, Friends and You. You in this context refers to the content owner. Use the commentThreadState property of the ListRelationship to determine the signed-in member’s ability to comment (or not).
accountStatus Required DEPRECATED AccountStatus

The member’s account status.
hideAds Required DEPRECATED boolean

true if member should not be shown ads.
twitterUsername string

The member’s Twitter username, if they have authenticated their account.
bioLbml string

The member’s bio in LBML. May contain the following HTML tags: <br> <strong> <em> <b> <i> <a href=""> <blockquote>.
location string

The member’s location.
website string

The member’s website URL. URLs are not validated, so sanitizing may be required.
backdrop Image

The member’s backdrop image at multiple sizes, sourced from the first film in the member’s list of favorite films, if available. Only returned for Patron members.
backdropFocalPoint number

The vertical focal point of the member’s backdrop image, if available. 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.
favoriteFilms FilmSummary[]

A summary of the member’s favorite films, up to a maximum of four.
pinnedFilmLists ListSummary[]

The film lists the member has pinned on their profile page, up to a maximum of two. Only returned for paying members.
pinnedReviews LogEntry[]

The reviews the member has pinned on their profile page, up to a maximum of two. Only returned for paying members.
links Required Link[]

A link to the member’s profile page on the Letterboxd website.
privateWatchlist boolean

Defaults to false for new accounts. Indicates whether the member has elected to hide their watchlist from other members.
featuredList ListSummary

A summary of the member’s featured list. Only returned for HQ members.
teamMembers MemberSummary[]

A summary of the member’s team members. Only returned for HQ members.
orgType enum ∈ { Society, Educator, Exhibitor, Festival, Single_Film, Genre, Association, Media_Publisher, Product_Platform, Podcast, Streamer, Studio }

The member’s organisation type. Only returned for HQ members.
bio string

The member’s bio formatted as HTML.

MemberAccount

Properties

emailAddress string

The member’s email address.
twoFactorAuthenticationEnabled boolean

Will be true if the member has enabled two-factor authentication.
emailAddressValidated boolean

Will be true if the member has validated their emailAddress via an emailed link.
privateAccount boolean

Defaults to false for new accounts. Indicates whether the member has elected for their content to appear in the API (other than in the /me endpoint).
includeInPeopleSection boolean

Defaults to true for new accounts. Indicates whether the member has elected to appear in the People section of the Letterboxd website.
privateWatchlist boolean

Defaults to false for new accounts. Indicates whether the member has elected to hide their watchlist from other members.DEPRECATED Found in member instead.
emailWhenFollowed boolean

Defaults to true for new accounts. Indicates whether the member has elected to receive an email notification when another member follows them.
emailAvailability boolean

Defaults to true for new accounts. Indicates whether the member has elected to receive an email notification when films on their watchlist become available to stream on one of their favorite services.
emailBuyAvailability boolean

Defaults to true for new accounts. Indicates whether the member has elected to receive an email notification when films on their watchlist become available to buy on one of their favorite services.
emailRentAvailability boolean

Defaults to true for new accounts. Indicates whether the member has elected to receive an email notification when films on their watchlist become available to rent on one of their favorite services.
emailComments boolean

Defaults to true for new accounts. Indicates whether the member has elected to receive email notifications when new comments are posted in threads they are subscribed to.
emailFromFollowedOnly boolean

Defaults to true for new accounts. Indicates whether the member has elected to receive email notifications for individual activity only from members they follow.
emailNews boolean

Defaults to true for new accounts. Indicates whether the member has elected to receive regular email news (including ‘Call Sheet’) from Letterboxd.
emailShelfLife boolean

Defaults to true for new accounts. Indicates whether the member has elected to receive the ‘Shelf Life’ newsletter from Letterboxd.
emailBestInShow boolean

Defaults to true for new accounts. Indicates whether the member has elected to receive the 'Best In Show' newsletter from Letterboxd.
emailEditorial boolean

Defaults to true for new accounts. Indicates whether the member has elected to receive personalized suggestions for Letterboxd editorial content.
emailRushes boolean

Defaults to true for new accounts. Indicates whether the member has elected to receive a weekly email digest of new and popular content (called ‘Rushes’).
emailPartnerMessages boolean

Defaults to true for new accounts. Indicates whether the member has elected to receive offers from trusted partners via Letterboxd.
devicesRegisteredForPushNotifications string[]

The list of device IDs that may receive push notifications for this account.
pushNotificationsForGeneralAnnouncements boolean

Defaults to true for new accounts. Indicates whether the member has elected to receive push notifications for platform and account alerts.
pushNotificationsForPartnerMessages boolean

Defaults to true for new accounts. Indicates whether the member has elected to receive push notifications with offers from trusted partners.
pushNotificationsForComments boolean

Defaults to true for new accounts. Indicates whether the member has elected to receive push notifications when new comments are posted in threads they are subscribed to.
pushNotificationsForListLikes boolean

Defaults to true for new accounts. Indicates whether the member has elected to receive push notifications when another member likes one of their lists.
pushNotificationsForReviewLikes boolean

Defaults to true for new accounts. Indicates whether the member has elected to receive push notifications when another member likes one of their reviews.
pushNotificationsForStoryLikes boolean

Defaults to true for new accounts. Indicates whether the member has elected to receive push notifications when another member likes one of their stories.
pushNotificationsForNewFollowers boolean

Defaults to true for new accounts. Indicates whether the member has elected to receive push notifications when another member follows them.
pushNotificationsForAvailability boolean

Defaults to true for new accounts. Indicates whether the member has elected to receive push notifications when films on a members watchlist become available to stream on one of their favorite services.
pushNotificationsForBuyAvailability boolean

Defaults to true for new accounts. Indicates whether the member has elected to receive push notifications when films on a members watchlist become available to buy on one of their favorite services.
pushNotificationsForRentAvailability boolean

Defaults to true for new accounts. Indicates whether the member has elected to receive push notifications when films on a members watchlist become available to rent on one of their favorite services.
pushNotificationsFromFollowedOnly boolean

Defaults to true for new accounts. Indicates whether the member has elected to receive push notifications for individual activity only from members they follow.
canComment boolean

Defaults to false for new accounts. Indicates whether the member has commenting privileges. Commenting is disabled on new accounts until the member’s emailAddress is validated. At present canComment is synonymous with emailAddressValidated (unless the member is suspended) but this may change in future.
suspended boolean

Indicates whether the member is suspended from commenting due to a breach of the Community Policy.
canCloneLists boolean

Indicates whether the member is able to clone other members’ lists. Determined by Letterboxd based upon memberStatus.
canChangeAppIcon boolean

Indicates whether the member is able to change their app icon. Determined by Letterboxd based upon memberStatus.
canFilterActivity boolean

Indicates whether the member is able to filter activity by type. Determined by Letterboxd based upon memberStatus.
membershipDaysRemaining int64 (number)

The number of days the member has left in their subscription. Only returned for paying members.
membershipWillAutoRenewViaIAP boolean

Indicates whether the member’s subscription is expected to auto-renew. Only returned for members who have subscribed through IAP.
hasActiveSubscription boolean

Indicates whether the member has an active subscription that will auto-renew. Will return false for members who did subscribe and then set their subscription to no longer renew, even if the original subscription period has not yet expired.
subscriptionType string

Indicates the member’s subscription type, possible values are apple, google or paddle. Only returned for members who have an active subscription.
member Required Member

Standard member details.
campaigns string[]

The list of campaigns this account is involved in.
adultContentPolicy enum ∈ { Always, Default }

The member’s adult content policy determing whether or not they see adult content. Supported options are Always or Default. Default means never show adult content.
posterMode PosterMode

The member’s poster mode determing whether or not they see custom posters. Supported options are All, Yours or None.
posterModeOptions PosterMode[]

The list of acceptable values that may be used for poster mode for this account
commentPolicy CommentPolicy

The member’s default policy determing who can post comments to their content. Supported options are Anyone, Friends and You. You in this context refers to the content owner. Use the commentThreadState property of the ListRelationship to determine the signed-in member’s ability to comment (or not).
accountStatus AccountStatus

The member’s account status.
hideAds boolean

true if member should not be shown ads.
showCustomPostersAds boolean

true if member should be shown ads for custom posters.
canHaveCustomPosters boolean

Indicates whether the member is able to customise film posters. Determined by Letterboxd based upon memberStatus.
canSeeStoryLikesComments boolean

Indicates whether the member is able to see likes and comments on stories.

MemberFilmRelationship

Properties

member Required MemberSummary

The member.
relationship Required FilmRelationship

The relationship details.

MemberFilmRelationshipsResponse

Properties

next string

The cursor to the next page of results.
items Required MemberFilmRelationship[]

The list of film relationships for members.
itemCount int32 (number)

MemberFilmViewingRelationship

Properties

member Required MemberSummary

The member.
relationship Required FilmRelationship

The relationship details.
logEntry LogEntrySummary

The log entry for the film.

MemberIdentifier

Properties

id Required string

The LID of the member.

MemberRelationship

Properties

following Required boolean

Will be true if the authenticated member follows the member identified by ID.
followedBy Required boolean

Will be true if the member identified by ID follows the authenticated member.
blocking Required boolean

Will be true if the authenticated member has blocked the member identified by ID.
blockedBy Required boolean

Will be true if the member identified by ID has blocked the authenticated member.

MemberRelationshipUpdateMessage

Properties

type Required enum ∈ { Error, Success }

The type of message.
code Required enum ∈ { BlockYourself, FollowYourself, FollowRateLimit, FollowBlockedMember, FollowMemberYouBlocked }

The error message code.
title Required string

The error message text in human-readable form.

MemberRelationshipUpdateRequest

Properties

following boolean

Set to true if the authenticated member wishes to follow the member identified by ID, or false if they wish to unfollow. A member may not follow their own account, or the account of a member they have blocked or that has blocked them.
blocking boolean

Set to true if the authenticated member wishes to block the member identified by ID, or false if they wish to unblock. A member may not block their own account.

MemberRelationshipUpdateResponse

Properties

data Required MemberRelationship

The response object.
messages Required MemberRelationshipUpdateMessage[]

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

MemberSearchItem

All of

AbstractSearchItem

Properties
member MemberSummary

The member returned by the search.

MemberSettingsUpdateMessage

Properties

type Required enum ∈ { Error, Success }

The type of message.
code Required enum ∈ { IncorrectCurrentPassword, BlankPassword, InvalidPassword, InvalidEmailAddress, EmailAddressInUse, InvalidFavoriteFilm, BioTooLong, InvalidPronounOption }

The error message code.
title Required string

The error message text in human-readable form.

MemberSettingsUpdateRequest

Properties

emailAddress string

The member’s email address.
currentPassword string

The member’s current password. Required when updating the password.
authenticationCode string

The member’s current authentication code. Required when updating the password for users with two-factor authentication enabled.
password string

The member’s new password.
givenName string

The given name of the member.
familyName string

The family name of the member.
pronoun string

The LID of the member’s preferred pronoun. Use the /members/pronouns endpoint to request all available pronouns.
commentPolicy string

The member’s default policy determing who can post comments to their content. Supported options are Anyone, Friends and You. You in this context refers to the content owner. Use the commentThreadState property of the ListRelationship to determine the signed-in member’s ability to comment (or not).
adultContentPolicy string

The member’s adult content policy determing whether or not they see adult content. Supported options are Always or Default. Default means never show adult content.
posterMode string

The member’s poster mode determing whether or not they see custom posters. Supported options are All, Yours or None.
location string

The member’s location.
website string

The member’s website URL. URLs are not validated, so sanitizing may be required.
bio string

The member’s bio in LBML. May contain the following HTML tags: <br> <strong> <em> <b> <i> <a href=""> <blockquote>. This field has a maximum size of 100,000 characters.
favoriteFilms string[]

The LIDs of the member’s favorite films, in order, up to a maximum of four.
privateAccount boolean

Set to true to prevent the member’s content from appearing in API requests other than the /me endpoint.
includeInPeopleSection boolean

Set to false to remove the account from the Members section of the Letterboxd website.
emailWhenFollowed boolean

Set to true if the member wishes to receive an email notification when another member follows them.
emailAvailability boolean
emailBuyAvailability boolean
emailRentAvailability boolean
emailComments boolean

Set to true if the member wishes to receive email notifications when new comments are posted in threads they are subscribed to.
emailFromFollowedOnly boolean

Set to true if the member wishes to receive email notifications for individual activity only from members they follow.
emailNews boolean

Set to true if the member wishes to receive regular email news (including ‘Call Sheet’) from Letterboxd.
emailShelfLife boolean

Set to true if the member wishes to receive the ‘Shelf Life’ newsletter from Letterboxd.
emailBestInShow boolean

Set to true if the member wishes to receive the 'Best In Show' newsletter from Letterboxd.
emailEditorial boolean

Set to true if the member wishes to receive personalized suggestions for Letterboxd editorial content.
emailRushes boolean

Set to true if the member wishes to receive a weekly email digest of new and popular content (called ‘Rushes’).
emailPartnerMessages boolean

Set to true if the member wishes to receive offers from trusted partners via Letterboxd.
pushNotificationsForGeneralAnnouncements boolean

Set to true if the member wishes to receive push notifications for platform and account alerts.
pushNotificationsForPartnerMessages boolean

Set to true if the member wishes to receive push notifications with offers from trusted partners.
pushNotificationsForComments boolean

Set to true if the member wishes to receive push notifications when new comments are posted in threads they are subscribed to.
pushNotificationsForReviewLikes boolean

Set to true if the member wishes to receive push notifications when another member likes one of their reviews.
pushNotificationsForListLikes boolean

Set to true if the member wishes to receive push notifications when another member likes one of their lists.
pushNotificationsForStoryLikes boolean

Set to true if the member wishes to receive push notifications when another member likes one of their stories.
pushNotificationsForNewFollowers boolean

Set to true if the member wishes to receive push notifications when another member follows them.
pushNotificationsForAvailability boolean
pushNotificationsForBuyAvailability boolean
pushNotificationsForRentAvailability boolean
pushNotificationsFromFollowedOnly boolean

Set to true if the member wishes to receive push notifications for individual activity only from members they follow.

MemberSettingsUpdateResponse

Properties

data Required MemberAccount

The response object.
messages Required MemberSettingsUpdateMessage[]

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

MembersResponse

Properties

next string

The cursor to the next page of results.
items Required MemberSummary[]

The list of members.
itemCount int32 (number)

MemberStatistics

Properties

member Required MemberIdentifier

The member for which statistics were requested.
counts Required MemberStatisticsCounts

The number of watches, ratings, likes, etc. for the member.
ratingsHistogram Required RatingsHistogramBar[]

A summary of the number of ratings the member has made for each increment between 0.5 and 5.0. Returns only the integer increments between 1.0 and 5.0 if the member never (or rarely) awards half-star ratings.
yearsInReview Required int32[]

A list of years the member has year-in-review pages for. Only supported for paying members.

MemberStatisticsCounts

Properties

filmLikes Required int32 (number)

The number of films the member has liked.
listLikes Required int32 (number)

The number of lists the member has liked.
reviewLikes Required int32 (number)

The number of reviews the member has liked.
storyLikes Required int32 (number)

The number of stories the member has liked.
watches Required int32 (number)

The number of films the member has watched. This is a distinct total — films with multiple log entries are only counted once.
ratings Required int32 (number)

The number of films the member has rated.
reviews Required int32 (number)

The number of films the member has reviewed.
diaryEntries Required int32 (number)

The number of entries the member has in their diary.
diaryEntriesThisYear Required int32 (number)

The number of entries the member has in their diary for the current year.
filmsInDiaryThisYear Required int32 (number)

The number of unique films the member has in their diary for the current year.
filmsInDiaryLastYear Required int32 (number)

The number of unique films the member has in their diary for the previous year. The year before the current year.
watchlist Required int32 (number)

The number of films the member has in their watchlist.
lists Required int32 (number)

The number of lists for the member. Includes unpublished lists if the request is made for the authenticated member.
unpublishedLists int32 (number)

The number of unpublished lists for the member. Only included if the request is made for the authenticated member.
accessedSharedLists int32 (number)

The number of shared lists accessed by the member. Only included if the request is made for the authenticated member.
followers Required int32 (number)

The number of members who follow the member.
following Required int32 (number)

The number of members the member is following.
listTags Required int32 (number)

The number of tags the member has used for lists.
filmTags Required int32 (number)

The number of tags the member has used for diary entries and reviews.

MemberStatus ENUM

Values

  • Crew
  • Alum
  • Hq
  • Patron
  • Pro
  • Member

MemberSummary

Properties

id Required string

The LID of the member.
username Required string

The member’s Letterboxd username. Usernames must be between 2 and 15 characters long and may only contain upper or lowercase letters, numbers or the underscore (_) character.
givenName string

The given name of the member.
familyName string

The family name of the member.
displayName Required string

A convenience method that returns the member’s given name and family name concatenated with a space, if both are set, or just their given name or family name, if one is set, or their username, if neither is set. Will never be empty.
shortName Required string

A convenience method that returns the member’s given name, if set, or their username. Will never be empty.
pronoun Pronoun

The member’s preferred pronoun. Use the /members/pronouns endpoint to request all available pronouns.
avatar Image

The member’s avatar image at multiple sizes. Avatar images to not have an enforced aspect ratio, so should be center-cropped to a square if they are not 1:1.
memberStatus Required MemberStatus

The member’s account type.
hideAdsInContent Required boolean

true if ads should not be shown on the member's content.
commentPolicy DEPRECATED CommentPolicy

The member’s default policy determing who can post comments to their content. Supported options are Anyone, Friends and You. You in this context refers to the content owner. Use the commentThreadState property of the ListRelationship to determine the signed-in member’s ability to comment (or not).
accountStatus Required DEPRECATED AccountStatus

The member’s account status.
hideAds Required DEPRECATED boolean

true if member should not be shown ads.

MemberTag

Properties

tag DEPRECATED string

Use displayTag instead.
code Required string

The tag code.
displayTag Required string

The tag text as entered by the tagger.
counts Required MemberTagCounts

Counts of the member’s uses of this tag.

MemberTagCounts

Properties

films Required int32 (number)

The number of films the member has used this tag on.
logEntries Required int32 (number)

The number of log entries the member has used this tag on.
diaryEntries Required int32 (number)

The number of diary entries the member has used this tag on.
reviews Required int32 (number)

The number of reviews the member has used this tag on.
lists Required int32 (number)

The number of lists the member has used this tag on.

MemberTagsResponse

Properties

items Required MemberTag[]

The list of tag items, ordered by frequency of use.
itemCount int32 (number)

Minigenre

Properties

code Required string

The identifying code for the minigenre.
name Required string

The name of the minigenre.

Nanogenre

Properties

code Required string

The identifying code for the nanogenre.
name Required string

The name of the nanogenre.

NewsItem

Properties

title Required string

The title of the news item.
image Image

The image.
url Required string

The URL of the news item.
shortDescription string

A short description of the news item in LBML. May contain the following HTML tags: <br> <strong> <em> <b> <i> <a href=""> <blockquote>.
longDescription string

A long description of the news item in LBML. May contain the following HTML tags: <br> <strong> <em> <b> <i> <a href=""> <blockquote>.
episode int32 (number)

The podcast episode number, if this news item is for a podcast
season int32 (number)

The podcast season number, if this news item is for a podcast

NewsResponse

Properties

next string

The cursor to the next page of results.
items Required NewsItem[]

The list of news items.
itemCount int32 (number)

PodcastSearchItem

All of

AbstractSearchItem

Properties
podcast NewsItem

The podcast.

PosterMode ENUM

Values

  • All
  • Theirs
  • Yours
  • None

Pronoun

Properties

id Required string

The LID for this pronoun.
label Required string

A label to describe this pronoun.
subjectPronoun Required string

The pronoun to use when the member is the subject.
objectPronoun Required string

The pronoun to use when the member is the object.
possessiveAdjective Required string

The adjective to use when describing a specified thing or things belonging to or associated with a member previously mentioned.
possessivePronoun Required string

The pronoun to use when referring to a specified thing or things belonging to or associated with a member previously mentioned.
reflexive Required string

The pronoun to use to refer back to the member.

PronounsResponse

Properties

items Pronoun[]

The list of pronouns.

RatingsHistogramBar

Properties

rating Required number

The rating increment between 0.5 and 5.0.
normalizedWeight Required number

The height of this rating increment’s entry in a unit-height histogram, normalized between 0.0 and 1.0. The increment(s) with the highest number of ratings will always return 1.0 (unless there are no ratings for the film).
count Required int32 (number)

The number of ratings made at this increment.

RegisterPushNotificationsRequest

Properties

deviceId Required string

The device ID.
deviceName string

The device name.
token Required string

The Firebase token.

RegisterRequest

Properties

username string

The username for the new account. Use the /auth/username-check endpoint to check availability.
password string

The password for the new account.
emailAddress string

The email address for the new account.
captchaResponse string

The captcha response value
acceptTermsOfUse boolean

Set to true if the person creating the account has agreed to being at least 16 years of age, and to accepting Letterboxd’s Terms of Use.

Release

Properties

type Required enum ∈ { Premiere, Theatrical_limited, Theatrical, Digital, Physical, TV }

The type of release.
country Required Country

The country of release.
language Language

The language of release.
certification string

The film's certification for release.
note string
releaseDate Required date (string)

The release date, in ISO 8601 format, i.e. YYYY-MM-DD

ReportCommentRequest

Properties

reason Required enum ∈ { Abuse, Spoilers, Spam, Plagiarism, Other }

The reason why the comment was reported.
message string

An optional, explanatory message to accompany the report. Required if the reason is Plagiarism or Other.

ReportFilmRequest

Properties

reason Required enum ∈ { Duplicate, NotAFilm, Image, Other }

The reason why the film was reported.
message string

An optional, explanatory message to accompany the report. Required if the reason is Duplicate or Other.

ReportListRequest

Properties

reason Required enum ∈ { Abuse, Spoilers, Spam, Plagiarism, Other }

The reason why the list was reported.
message string

An optional, explanatory message to accompany the report. Required if the reason is Plagiarism or Other.

ReportMemberRequest

Properties

reason Required enum ∈ { AbusiveAccount, HatefulAccount, ManipulativeAccount, OffensiveAccount, ParodyAccount, PiracyAccount, PlagiaristAccount, SolicitousAccount, SpamAccount, Other }

The reason why the member was reported.
message string

An optional, explanatory message to accompany the report. Required if the reason is Other.

ReportReviewRequest

Properties

reason Required enum ∈ { Abuse, Spoilers, Spam, Plagiarism, Other }

The reason why the review was reported.
message string

An optional, explanatory message to accompany the report. Required if the reason is Plagiarism or Other.

Review

Properties

lbml Required string

The review text in LBML. May contain the following HTML tags: <br> <strong> <em> <b> <i> <a href=""> <blockquote>.
containsSpoilers Required boolean

Will be true if the member has indicated that the review field contains plot spoilers for the film.
spoilersLocked Required boolean

Will be true if the spoilers flag has been locked by a moderator.
moderated Required boolean

Will be true if the review has been removed by a moderator.
whenReviewed Required date-time (string)

The timestamp when this log entry’s review was first published, in ISO 8601 format with UTC timezone, i.e. YYYY-MM-DDThh:mm:ssZ
text Required string

The review text formatted as HTML.

ReviewActivity

All of

AbstractActivity

Properties
review LogEntry

The log entry associated with this activity

ReviewComment

All of

AbstractComment

Properties
blockedByOwner boolean

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

The review on which the comment was posted.

ReviewCommentActivity

All of

AbstractActivity

Properties
review LogEntry

The review associated with the activity.
comment ReviewComment

The comment associated with the activity.

ReviewCommentsResponse

Properties

next string

The cursor to the next page of results.
items Required ReviewComment[]

The list of comments.
itemCount int32 (number)

ReviewIdentifier

Properties

id Required string

The LID of the log entry.

ReviewLikeActivity

All of

AbstractActivity

Properties
review LogEntry

The review associated with the activity.

ReviewMemberRelationship ENUM

Values

  • Ignore
  • Owner
  • Liked

ReviewRelationship

Properties

liked Required boolean

Will be true if the member likes the review (via the ‘heart’ icon). A member may not like their own review.
subscribed Required boolean

Will be true if the member is subscribed to comment notifications for the review
subscriptionState Required CommentSubscriptionState

Defaults to Subscribed for the review’s author, and NotSubscribed for other members. The subscription value may change when a member (other than the owner) posts a comment, as follows: the member will become automatically Subscribed unless they have previously Unsubscribed from the comment thread via the web interface or API, or unless they have disabled comment notifications in their account settings. NotSubscribed and Unsubscribed are maintained as separate states so the UI can, if needed, indicate to the member how their subscription state will be affected if/when they post a comment.
commentThreadState Required CommentThreadState

The authenticated member’s state with respect to adding comments for this review.Banned means the Letterboxd community managers have restricted the member’s ability to post comments.Blocked means the owner has blocked the member from posting comments.BlockedThem means the member has blocked the owner and is therefore unable to post comments.CanComment means the authenticated member is authorized to post a comment (also known as a “reply”). All other values mean the authenticated member is not authorized to post a comment.Closed means the owner has closed the comment thread to all other members.FriendsOnly means the owner is only accepting comments from members they follow.Moderated means the Letterboxd community managers have removed the content (applies to reviews only).NotCommentable means that comments may not be posted to this thread.NotValidated means the owner has not validated their email address.

ReviewRelationshipUpdateMessage

Properties

type Required enum ∈ { Error, Success }

The type of message.
code Required enum ∈ { LikeBlockedContent, LikeOwnReview, LikeRateLimit, LikeRemovedReview, LikeLogEntryWithoutReview, SubscribeWhenOptedOut, SubscribeToContentYouBlocked, SubscribeToBlockedContent }

The error message code.
title Required string

The error message text in human-readable form.

ReviewRelationshipUpdateRequest

Properties

liked boolean | null

Set to true if the member likes the review (via the ‘heart’ icon). A member may not like their own review.
subscribed boolean | null

Set to true to subscribe the member to comment notifications for the review, or false to unsubscribe them. A value of true will be ignored if the member has disabled comment notifications in their account settings.

ReviewRelationshipUpdateResponse

Properties

data Required ReviewRelationship

The response object.
messages Required ReviewRelationshipUpdateMessage[]

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

ReviewResponseActivity

All of

AbstractActivity

Properties
review LogEntry

The review associated with the activity.
response string

The comment associated with the activity.

ReviewSearchItem

All of

AbstractSearchItem

Properties
review LogEntry

Details of the review.

ReviewStatistics

Properties

logEntry Required ReviewIdentifier

The log entry for which statistics were requested.
counts Required ReviewStatisticsCounts

The number of comments and likes for the review.

ReviewStatisticsCounts

Properties

comments Required int32 (number)

The number of comments for the review.
likes Required int32 (number)

The number of members who like the review.

ReviewUpdateResponse

Properties

data Required LogEntry

The response object.
messages Required LogEntryUpdateMessage[]

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

SearchResponse

Properties

next string

The cursor to the next page of results.
items Required AbstractSearchItem[]

The list of search results.
itemCount int32 (number)

SearchResultType ENUM

Values

  • ContributorSearchItem
  • FilmSearchItem
  • ListSearchItem
  • MemberSearchItem
  • ReviewSearchItem
  • TagSearchItem
  • StorySearchItem
  • ArticleSearchItem
  • PodcastSearchItem

Service

Properties

id Required string

The LID of the service.
name Required string

The name of the service.
icon url (string)

The URL of the thumbnail image for the service.

SharePolicy ENUM

Values

  • Anyone
  • Friends
  • You

Shift72AuthResponse

Properties

authToken string

StoriesResponse

Properties

next string

The cursor to the next page of results.
items Required StorySummary[]

The list of stories.
itemCount int32 (number)

Story

Properties

id Required string

The LID of the story.
name Required string

The name of the story.
author Required MemberSummary

The member who published the story.
url string

The external URL linked to by the story (if applicable).
source string

The publication name for the story (if applicable).
videoUrl string

The URL of the story’s video (if applicable).
bodyHtml string

The story body formatted as HTML. The text is a preview extract, and may be truncated if it’s too long.
bodyLbml string

The story body formatted as LBML. May contain the following HTML tags: <br> <strong> <em> <b> <i> <a href=""> <blockquote>. The text is a preview extract, and may be truncated if it’s too long.
whenUpdated date-time (string)

ISO 8601 format with UTC timezone, i.e. YYYY-MM-DDThh:mm:ssZ
whenCreated Required date-time (string)

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

The story’s hero image, in multiple resolutions.
pinned Required boolean

If this story has been pinned by its author, pinned will be true.
commentPolicy CommentPolicy

The policy determining who can post comments to the story. You in this context refers to the content owner. Use the commentThreadState property of the ListRelationship to determine the signed-in member’s ability to comment (or not).

StoryActivity

All of

AbstractActivity

Properties
story StorySummary

The story associated with the activity.

StoryComment

All of

AbstractComment

Properties
blockedByOwner boolean

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

The story on which the comment was posted.

StoryCommentActivity

All of

AbstractActivity

Properties
story StorySummary

The story associated with the activity.
comment StoryComment

The comment associated with the activity.

StoryCommentsResponse

Properties

next string

The cursor to the next page of results.
items Required StoryComment[]

The list of comments.
itemCount int32 (number)

StoryIdentifier

Properties

id Required string

The LID of the story.

StoryLikeActivity

All of

AbstractActivity

Properties
story StorySummary

The story associated with the activity.

StoryMemberRelationship ENUM

Values

  • Owner
  • Liked

StoryRelationship

Properties

liked Required boolean

Will be true if the member likes the story (via the ‘heart’ icon). A member may not like their own story.
subscribed Required boolean

Will be true if the member is subscribed to comment notifications for the story
subscriptionState Required CommentSubscriptionState

Defaults to Subscribed for the story's owner, and NotSubscribed for other members. The subscription value may change when a member (other than the owner) posts a comment, as follows: the member will become automatically Subscribed unless they have previously Unsubscribed from the comment thread via the web interface or API, or unless they have disabled comment notifications in their account settings. NotSubscribed and Unsubscribed are maintained as separate states so the UI can, if needed, indicate to the member how their subscription state will be affected if/when they post a comment.
commentThreadState Required CommentThreadState

The authenticated member’s state with respect to posting comments to the story.Banned means the Letterboxd community managers have restricted the member’s ability to post comments.Blocked means the owner has blocked the member from posting comments.BlockedThem means the member has blocked the owner and is therefore unable to post comments.CanComment means the authenticated member is authorized to post a comment (also known as a “reply”). All other values mean the authenticated member is not authorized to post a comment.Closed means the owner has closed the comment thread to all other members.FriendsOnly means the owner is only accepting comments from members they follow.Moderated means the Letterboxd community managers have removed the content (applies to reviews only).NotCommentable means that comments may not be posted to this thread.NotValidated means the owner has not validated their email address.

StoryRelationshipUpdateMessage

Properties

type Required enum ∈ { Error, Success }

The type of message.
code Required enum ∈ { LikeBlockedContent, LikeOwnStory, LikeRateLimit, SubscribeWhenOptedOut, SubscribeToContentYouBlocked, SubscribeToBlockedContent }

The error message code.
title Required string

The error message text in human-readable form.

StoryRelationshipUpdateRequest

Properties

liked boolean | null

Set to true if the member likes the story (via the ‘heart’ icon). A member may not like their own story.
subscribed boolean | null

Set to true to subscribe the member to comment notifications for the story, or false to unsubscribe them. A value of true will be ignored if the member has disabled comment notifications in their account settings.

StoryRelationshipUpdateResponse

Properties

data Required StoryRelationship

The response object.
messages Required StoryRelationshipUpdateMessage[]

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

StorySearchItem

All of

AbstractSearchItem

Properties
story StorySummary

The story.

StoryStatistics

Properties

story Required StoryIdentifier

The story for which statistics were requested.
counts Required StoryStatisticsCounts

The number of comments and likes for the list.

StoryStatisticsCounts

Properties

comments Required int32 (number)

The number of comments for the list.
likes Required int32 (number)

The number of members who like the list.

StorySummary

Properties

id Required string

The LID of the story.
name Required string

The name of the story.
author Required MemberSummary

The member who published the story.
url string

The external URL linked to by the story (if applicable).
source string

The publication name for the story (if applicable).
videoUrl string

The URL of the story’s video (if applicable).
bodyHtml string

The story body formatted as HTML. The text is a preview extract, and may be truncated if it’s too long.
bodyLbml string

The story body formatted as LBML. May contain the following HTML tags: <br> <strong> <em> <b> <i> <a href=""> <blockquote>. The text is a preview extract, and may be truncated if it’s too long.
bodyTruncated boolean

Will be true if the story body was truncated because it’s very long.
whenUpdated date-time (string)

ISO 8601 format with UTC timezone, i.e. YYYY-MM-DDThh:mm:ssZ
whenCreated Required date-time (string)

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

The story’s hero image, in multiple resolutions.
pinned boolean

If this story has been pinned by its author, pinned will be true.

StoryUpdateMessage

Properties

type Required enum ∈ { Error, Success }

The type of message.
code Required enum ∈ { StoryNameTooLong, StoryNameIsBlank, StoryWithNoText, StoryIsTooLong, StoryWithNoImage }

The error message code.
title Required string

The error message text in human-readable form.

StoryUpdateRequest

Properties

commentPolicy CommentPolicy | null

The policy determining who can post comments to the story. You in this context refers to the content owner. Use the commentThreadState property of the ListRelationship to determine the signed-in member’s ability to comment (or not).

StoryUpdateResponse

Properties

data Required Story

The response object.
messages Required StoryUpdateMessage[]

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

Tag

Properties

tag DEPRECATED string

Use displayTag instead.
code Required string

The tag code.
displayTag Required string

The tag text as entered by the tagger.

TagCheckRequest

Properties

type Required string

The type of tag to update (viewings or lists).
tagCode Required string

The code of the tag being checked.

TagCheckResponse

Properties

count Required int32 (number)

The number of taggings for the current user matching the new tag name.
type string

The type of tag to update (viewings or lists).
newTagCode string

TagDeleteRequest

Properties

type Required string

The type of tag to delete (viewings or lists).
tagCode Required string

The code of the tag to delete.
rawTag Required string

The raw value of the tag to delete.

TagSearchItem

All of

AbstractSearchItem

Properties
tag Tag

The tag.

TagsResponse

Properties

items Required string[]

The list of tags, ordered by frequency of use.
itemCount int32 (number)

TagUpdateRequest

Properties

type Required string

The type of tag to update (viewings or lists).
tagCode Required string

The code of the tag to update.
rawTag Required string

The raw value of the tag to update.
newTagCode Required string

The code of the tag following the update (may result in a merge if the code already exists).

Theme

Properties

code Required string

The identifying code for the theme.
name Required string

The name of the theme.

TopicsResponse

Properties

items Required AListTopic[]

The list of topics.

TreasureHuntItem

Properties

locationHint Required string

The location hint
name Required string

The name
image Required Image

The image
found Required boolean

Whether the item has been marked as found by the current user
itemId string

The item id
nonce string

The collect nonce
token string

The collect token
actionUrl Required string

The action URL

UploadUrlResponse

Properties

url Required string

A single-use url for uploading a data file.

UsernameCheckResponse

Properties

result Required enum ∈ { Available, NotAvailable, TooShort, TooLong, Invalid }

Will be Available if the username is available to register, or NotAvailable if used by another member (or attached to a deactivated account, or otherwise reserved). May return an appropriate error value if the username doesn’t meet Letterboxd’s requirements: Usernames must be between 2 and 15 characters long and may only contain upper or lowercase letters, numbers or the underscore (_) character.

WatchlistActivity

All of

AbstractActivity

Properties
film FilmSummary

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