Overview

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

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

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

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

In all cases the response from an endpoint will be a JSON object, with HTTP status codes indicating successful results and error states. Where cursor pagination is provided, there is an enforced limit of 100,000 objects returned in the paginated data, to discourage API consumers from copying our complete dataset. Parameters and endpoints marked as ‘First Party’ are only available to Letterboxd’s own apps, due to licensing restrictions.

Authorization

The Letterboxd API uses standard OAuth 2 Resource Owner, Client Credentials, Authorization Code and Refresh Token authorization flows to grant access via an access token. Resource Owner tokens are for first-party use only, and may be refreshed at regular intervals to keep the member signed in. Third-party API consumers must use the Client Credentials or Authorization Code flows instead of the Resource Owner grant (Client Credentials returns publicly available data, while Authorization Code is required for any operation that requires member authorization, such as accessing private data or modifying a member’s data). When generating or refreshing an access token, make a form request to the /auth/token endpoint with Content-Type: application/x-www-form-urlencoded and Accept: application/json headers, and request-body parameters as follows:

Resource Owner FIRST PARTY LEGACY

grant_type Required string Use value: password
username Required string The member’s username or email address.
password Required string The member’s password.
scope string Not required for first-party API clients. Legacy API consumers may use this parameter to request additional scopes, over and above the default scopes. See Scopes for more details.
client_id Required string Your API key.
client_secret Required string Your API secret.

Client Credentials

grant_type Required string Use value: client_credentials
client_id Required string Your API key.
client_secret Required string Your API secret.

Authorization Code

grant_type Required string Use value: authorization_code
code Required string The authorization code returned from the grant flow.
redirect_uri Required string The URI used when initiating the authorization-code flow.
client_id Required string Your API key.
client_secret Required string Your API secret.

Refresh a token

grant_type Required string Use value: refresh_token
refresh_token Required string The member’s current refresh-token value.

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

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

Scopes

A scope is a security requirement that must be met before you can use an endpoint. Scopes are tied to an access token. Letterboxd offers the scopes detailed here.

Some scopes are automatically granted based on the auth flow in use, and you do not need to request authorisation from the member for these defaults. If you need to request additional scopes beyond the defaults, these will be shown to the person using your app, and granted if they agree to the scopes being sought.

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

Authorization Code Flow

Obtaining an authorization code follows a standard OAuth2 code flow. To use this flow, you must apply for and receive an API key. With the correct credentials, make a GET or POST request to the /authorize endpoint, using the following query or form params:

response_type Required string Use value: code
client_id Required string Your API key.
redirect_uri Required string The URI to which the code will be sent. This must exactly match the URI that is registered with your API credentials.
scope string The scopes you wish to authorize for the access token. These scopes will be presented to the authorizing member for approval. See Scopes for more details.
state Recommended string Useful for preventing CSRF attacks. If you include this value, it will be returned along with the authorization code.

A valid request will return a page on which the currently signed-in member can approve the requested scopes. If there is no signed-in member, a sign-in page is returned. If the member approves access to the scopes, the request is redirected to the provided URI with the authorization code as a path parameter (and the state value, if provided).

Once you have an authorization code, you may redeem it for an access token.

OpenID Connect

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

Request signing

Letterboxd previously required signing for all API requests. Signing is no longer required. Legacy API consumers should refer to the Authorization section for further details.

Security definitions

oauth

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.

Endpoints

POST /apple-iap/subscription

Process an Apple In-app Purchase receipt.

Response

200

Success

AppleIAPSubscriptionResponse
401

There is no authenticated member

Security

oauth user

GET /auth/authorize

Initiate the authorize-code-grant flow.

See the Authorization Code Flow for more details.

Response

200

The scope-approval page.

400

Something was wrong with your code-grant form.

OAuthError

POST /auth/authorize

Initiate the authorize-code-grant flow.

See Authorization Code Flow for more details.

Response

200

The scope-approval page.

400

Something was wrong with your code-grant form.

OAuthError

POST /auth/forgotten-password-request

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

Response

204

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

400

Bad request

429

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

Security

oauth

GET /auth/get-login-token

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

Response

200

Success

LoginTokenResponse
400

Bad request

401

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

Security

oauth user:owner

GET /auth/get-upload-url

Generate a single-use upload url for the current member, which can be used to upload a data file for the member.

Response

200

Success

UploadUrlResponse
400

Bad request

401

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

POST /auth/revoke

Response

default

successful operation

POST /auth/token

Apply for an authorization token using one of the supported authorization flows.

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

Response

200

Success

AccessToken
400

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

OAuthError

GET /auth/username-check

Check if a username is available to register.

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

Parameters

username Required query string

The username to check.

Response

200

Success

UsernameCheckResponse

Security

oauth

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.

Parameters

id Required path string

The LID of the comment/​reply.

Response

204

Success

400

Bad request

401

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

403

The window for deleting this comment has expired

404

No comment matches the specified ID

PATCH /comment/{id}

Update the message portion of a comment.

Parameters

id Required path string

The LID of the comment/​reply.

Response

200

Completed, possibly with messages

CommentUpdateResponse
401

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

404

No comment matches the specified ID

POST /comment/{id}/report

Report a comment by ID.

Parameters

id Required path string

The LID of the comment/​reply.

Response

204

Success

401

There is no authenticated member

404

No comment matches the specified ID

GET /contributor/{id}

Get details about a film contributor by ID.

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

Parameters

id Required path string

The LID of the contributor.

Response

200

Success

Contributor
404

No contributor matches the specified ID

Security

oauth

GET /contributor/{id}/contributions

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

Use the ‘next’ cursor to move through the list

Parameters

id Required path string

The LID of the contributor.

cursor query string

The pagination cursor.

perPage query integer

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

filmId query
string[]

multiple parameters (filmId=aaa&filmId=bbb)

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

genre query string

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

similarTo query string

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

theme query string

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

minigenre query string

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

nanogenre query string

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

includeGenre query
string[]

multiple parameters (includeGenre=aaa&includeGenre=bbb)

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

excludeGenre query
string[]

multiple parameters (excludeGenre=aaa&excludeGenre=bbb)

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

country query string

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

language query string

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

decade query integer

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

year query integer

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

service query string

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

availabilityType query
string[]

multiple parameters (availabilityType=aaa&availabilityType=bbb)

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

exclusive query boolean

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

unavailable query boolean

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

includeOwned query boolean

Set to true to include films that the user owns.

negate query boolean

Set to true to invert the current service filtering options.

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

multiple parameters (where=aaa&where=bbb)

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

member query string

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

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

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

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

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

tag query string

DEPRECATED Use tagCode instead.

tagCode query string

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

tagger query string

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

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

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

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

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

type query enum ∈ {Director, CoDirector, AdditionalDirecting, Actor, Producer, ExecutiveProducer, Writer, OriginalWriter, Casting, Editor, Cinematography, AdditionalPhotography, ProductionDesign, ArtDirection, SetDecoration, SpecialEffects, VisualEffects, Stunts, Choreography, Composer, Songs, Sound, Costumes, MakeUp, Hairstyling, Studio}

The type of contribution.

Response

200

Success

FilmContributionsResponse
404

No contributor matches the specified ID

Security

oauth

GET /film-collection/{id}

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

Parameters

id Required path string

The LID of the film collection.

filmId query
string[]

multiple parameters (filmId=aaa&filmId=bbb)

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

genre query string

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

similarTo query string

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

theme query string

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

minigenre query string

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

nanogenre query string

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

includeGenre query
string[]

multiple parameters (includeGenre=aaa&includeGenre=bbb)

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

excludeGenre query
string[]

multiple parameters (excludeGenre=aaa&excludeGenre=bbb)

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

country query string

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

language query string

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

decade query integer

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

year query integer

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

service query string

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

availabilityType query
string[]

multiple parameters (availabilityType=aaa&availabilityType=bbb)

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

exclusive query boolean

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

unavailable query boolean

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

includeOwned query boolean

Set to true to include films that the user owns.

negate query boolean

Set to true to invert the current service filtering options.

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

multiple parameters (where=aaa&where=bbb)

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

member query string

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

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

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

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

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

tag query string

DEPRECATED Use tagCode instead.

tagCode query string

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

tagger query string

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

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

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

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

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

Response

200

Success

FilmCollection
404

No film collection matches the specified ID

Security

oauth

GET /film/{id}

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

Parameters

id Required path string

The LID of the film.

member query string

Specify the LID of a member to honor any custom-poster settings the member may have for the film, when viewed within the context of their profile or content.

Response

200

Success

Film
404

No film matches the specified ID

Security

oauth

GET /film/{id}/availability

FIRST PARTY Get availability data for a film by ID.

Parameters

id Required path string

The LID of the film.

Response

200

Success

FilmAvailabilityResponse
404

No film matches the specified ID

Security

oauth

GET /film/{id}/friends

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

Parameters

id Required path string

The LID of the film.

Response

200

Success

FilmRelationship
401

There is no authenticated member

404

No film matches the specified ID

Security

oauth user

GET /film/{id}/me

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

Parameters

id Required path string

The LID of the film.

Response

200

Success

FilmRelationship
401

There is no authenticated member

404

No film matches the specified ID

Security

oauth user

PATCH /film/{id}/me

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

Parameters

id Required path string

The LID of the film.

Response

200

Success

FilmRelationshipUpdateResponse
401

There is no authenticated member

404

No film matches the specified ID

GET /film/{id}/members

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

Parameters

id Required path string

The LID of the film.

cursor query string

The pagination cursor.

perPage query integer

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

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

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

member query string

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

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

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

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

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

Response

200

Success

MemberFilmRelationshipsResponse
404

No film matches the specified ID

Security

oauth

POST /film/{id}/report

Report a film by ID.

Parameters

id Required path string

The LID of the film.

Response

204

Success

401

There is no authenticated member

404

No film matches the specified ID

GET /film/{id}/statistics

Get statistical data about a film by ID.

Parameters

id Required path string

The LID of the film.

member query string

Specify the LID of a member to return statistics for members followed by that member.

Response

200

Success

FilmStatistics
404

No film matches the specified ID

Security

oauth

GET /films

A cursored window over the list of films.

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

Parameters

cursor query string

The pagination cursor.

perPage query integer

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

filmId query
string[]

multiple parameters (filmId=aaa&filmId=bbb)

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

genre query string

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

similarTo query string

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

theme query string

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

minigenre query string

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

nanogenre query string

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

includeGenre query
string[]

multiple parameters (includeGenre=aaa&includeGenre=bbb)

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

excludeGenre query
string[]

multiple parameters (excludeGenre=aaa&excludeGenre=bbb)

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

country query string

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

language query string

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

decade query integer

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

year query integer

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

service query string

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

availabilityType query
string[]

multiple parameters (availabilityType=aaa&availabilityType=bbb)

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

exclusive query boolean

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

unavailable query boolean

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

includeOwned query boolean

Set to true to include films that the user owns.

negate query boolean

Set to true to invert the current service filtering options.

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

multiple parameters (where=aaa&where=bbb)

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

member query string

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

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

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

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

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

tag query string

DEPRECATED Use tagCode instead.

tagCode query string

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

tagger query string

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

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

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

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

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

Response

200

Success

FilmsResponse

Security

oauth

GET /films/autocomplete

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

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

Parameters

perPage query integer

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

input Required query string

The word, partial word or phrase to match against.

adult query boolean

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

Response

200

Success

FilmsAutocompleteResponse

Security

oauth

GET /films/availability-types

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

Availability types are returned in alphabetical order.

Response

200

Success

AvailabilityTypesResponse

GET /films/countries

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

Countries are returned in alphabetical order.

Response

200

Success

CountriesResponse

Security

oauth

GET /films/film-services

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

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

Response

200

Success

FilmServicesResponse

Security

oauth

GET /films/genres

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

Genres are returned in alphabetical order.

Response

200

Success

GenresResponse

Security

oauth

GET /films/languages

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

Languages are returned in alphabetical order.

Response

200

Success

LanguagesResponse

Security

oauth

POST /google-billing/subscription

Process an Google Purchase purchase token.

Response

200

Success

GoogleBillingSubscriptionResponse
401

There is no authenticated member

Security

oauth user

DELETE /list/{id}

Delete a list by ID.

Parameters

id Required path string

The LID of the list.

Response

204

Success

400

Bad request

401

There is no authenticated member

403

The authenticated member does not own the specified list

404

No list matches the specified ID

GET /list/{id}

Get details of a list by ID.

Parameters

id Required path string

The LID of the list.

Response

200

Success

List
404

No list matches the specified ID

Security

oauth

PATCH /list/{id}

Update a list by ID.

Parameters

id Required path string

The LID of the list.

Response

200

Success

ListUpdateResponse
400

Bad request

401

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

404

No list matches the specified ID

GET /list/{id}/comments

A cursored window over the comments for a list.

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

Parameters

id Required path string

The LID of the list.

cursor query string

The pagination cursor.

perPage query integer

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

sort query enum ∈ {Date, DateLatestFirst, Updates}

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

includeDeletions query boolean

Use this to discover any comments that were deleted.

Response

200

Success

ListCommentsResponse
404

No list matches the specified ID

Security

oauth

POST /list/{id}/comments

Create a comment on a list.

Parameters

id Required path string

The LID of the list.

Response

201

Success

ListComment
204

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

400

Bad request

401

There is no authenticated member

403

The authenticated member is not authorized to comment on this list

404

No list matches the specified ID

GET /list/{id}/entries

Get entries for a list by ID.

Parameters

id Required path string

The LID of the list.

cursor query string

The pagination cursor.

perPage query integer

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

filmId query
string[]

multiple parameters (filmId=aaa&filmId=bbb)

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

genre query string

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

similarTo query string

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

theme query string

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

minigenre query string

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

nanogenre query string

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

includeGenre query
string[]

multiple parameters (includeGenre=aaa&includeGenre=bbb)

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

excludeGenre query
string[]

multiple parameters (excludeGenre=aaa&excludeGenre=bbb)

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

country query string

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

language query string

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

decade query integer

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

year query integer

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

service query string

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

availabilityType query
string[]

multiple parameters (availabilityType=aaa&availabilityType=bbb)

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

exclusive query boolean

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

unavailable query boolean

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

includeOwned query boolean

Set to true to include films that the user owns.

negate query boolean

Set to true to invert the current service filtering options.

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

multiple parameters (where=aaa&where=bbb)

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

member query string

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

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

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

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

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

tag query string

DEPRECATED Use tagCode instead.

tagCode query string

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

tagger query string

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

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

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

sort query enum ∈ {ListRanking (default), WhenAddedToList, WhenAddedToListEarliestFirst, Shuffle, FilmName, OwnerRatingHighToLow, OwnerRatingLowToHigh, OwnerDiaryLatestFirst, OwnerDiaryEarliestFirst, AuthenticatedMemberRatingHighToLow, AuthenticatedMemberRatingLowToHigh, AuthenticatedMemberDiaryLatestFirst, AuthenticatedMemberDiaryEarliestFirst, AuthenticatedMemberBasedOnLiked, AuthenticatedMemberRelatedToLiked, MemberRatingHighToLow, MemberRatingLowToHigh, MemberDiaryLatestFirst, MemberDiaryEarliestFirst, AverageRatingHighToLow, AverageRatingLowToHigh, RatingHighToLow, RatingLowToHigh, ReleaseDateLatestFirst, ReleaseDateEarliestFirst, FilmDurationShortestFirst, FilmDurationLongestFirst, FilmPopularity, FilmPopularityThisWeek, FilmPopularityThisMonth, FilmPopularityThisYear}

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

Response

200

Success

ListEntriesResponse
404

No list matches the specified ID

Security

oauth

GET /list/{id}/me

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

Parameters

id Required path string

The LID of the list.

Response

200

Success

ListRelationship
401

There is no authenticated member

404

No list matches the specified ID

Security

oauth user

PATCH /list/{id}/me

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

Parameters

id Required path string

The LID of the list.

Response

200

Success

ListRelationshipUpdateResponse
401

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

404

No list matches the specified ID

POST /list/{id}/report

Report a list by ID.

Parameters

id Required path string

The LID of the list.

Response

204

Success

401

There is no authenticated member

404

No list matches the specified ID

GET /list/{id}/statistics

Get statistical data about a list by ID.

Parameters

id Required path string

The LID of the list.

Response

200

Success

ListStatistics
404

No list matches the specified ID

Security

oauth

GET /lists

A cursored window over a list of lists.

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

Parameters

cursor query string

The pagination cursor.

perPage query integer

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

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

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

film query string

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

clonedFrom query string

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

tag query string

DEPRECATED Use tagCode instead.

tagCode query string

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

tagger query string

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

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

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

member query string

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

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

Must be used in conjunction with member. Defaults to Owner, which returns lists owned by the member. Use Liked to return lists liked by the member or Accessed to return shared lists that have been viewed by the member.

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

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

where query
enum[] ∈ {Clean, Published, NotPublished, NotPublishedOrShared, SharedAnyone, SharedFriends, Owned}

multiple parameters (where=aaa&where=bbb)

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

filter query
enum[] ∈ {NoDuplicateMembers}

multiple parameters (filter=aaa&filter=bbb)

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

filmsOfNote query
string[]

multiple parameters (filmsOfNote=aaa&filmsOfNote=bbb)

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

Response

200

Success

ListsResponse
400

Bad request

403

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

404

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

Security

oauth

PATCH /lists

Add one or more films to one or more lists.

Response

200

Success

ListAdditionResponse
400

Bad request

401

There is no authenticated member

POST /lists

Create a list.

Response

200

Success

ListCreateResponse
400

Bad request

401

There is no authenticated member

GET /lists/topics

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

Response

200

Success

TopicsResponse

Security

oauth

GET /log-entries

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

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

Parameters

cursor query string

The pagination cursor.

perPage query integer

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

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

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

film query string

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

member query string

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

memberRelationship query enum ∈ {Ignore, Owner, Liked}

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

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

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

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

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

year query integer

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

month query integer

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

week query integer

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

day query integer

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

minRating query number

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

maxRating query number

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

filmDecade query integer

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

filmYear query integer

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

genre query string

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

includeGenre query
string[]

multiple parameters (includeGenre=aaa&includeGenre=bbb)

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

excludeGenre query
string[]

multiple parameters (excludeGenre=aaa&excludeGenre=bbb)

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

country query string

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

language query string

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

tag query string

DEPRECATED Use tagCode instead.

tagCode query string

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

tagger query string

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

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

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

service query string

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

availabilityType query
string[]

multiple parameters (availabilityType=aaa&availabilityType=bbb)

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

exclusive query boolean

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

unavailable query boolean

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

includeOwned query boolean

Set to true to include films that the user owns.

negate query boolean

Set to true to invert the current service filtering options.

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

multiple parameters (where=aaa&where=bbb)

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

filter query
enum[] ∈ {NoDuplicateMembers}

multiple parameters (filter=aaa&filter=bbb)

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

Response

200

Success

LogEntriesResponse
404

Film or Member not found

Security

oauth

POST /log-entries

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

Response

201

Success

LogEntry
204

No action was taken, as the log entry already exists

400

Bad request

401

There is no authenticated member

404

The film was not found

DELETE /log-entry/{id}

Delete a log entry by ID.

Parameters

id Required path string

The LID of the log entry.

Response

204

Success

400

Bad request

401

There is no authenticated member

403

The authenticated member is not authorized to delete this log entry

404

No log entry matches the specified ID

GET /log-entry/{id}

Get details about a log entry by ID.

Parameters

id Required path string

The LID of the log entry.

Response

200

Success

LogEntry
404

No log entry matches the specified ID

Security

oauth

PATCH /log-entry/{id}

Update a log entry by ID.

Parameters

id Required path string

The LID of the log entry.

Response

200

Success

ReviewUpdateResponse
400

Bad request

401

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

404

No log entry matches the specified ID

GET /log-entry/{id}/comments

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

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

Parameters

id Required path string

The LID of the log entry.

cursor query string

The pagination cursor.

perPage query integer

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

sort query enum ∈ {Date, DateLatestFirst, Updates}

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

includeDeletions query boolean

Use this to discover any comments that were deleted.

Response

200

Success

ReviewCommentsResponse
404

No log entry matches the specified ID

Security

oauth

POST /log-entry/{id}/comments

Create a comment on a review.

Parameters

id Required path string

The LID of the log entry.

Response

201

Success

ReviewComment
204

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

400

Bad request

401

There is no authenticated member

403

The authenticated member is not authorized to comment on this review

404

No film matches the specified ID

GET /log-entry/{id}/me

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

Parameters

id Required path string

The LID of the log entry.

Response

200

Success

ReviewRelationship
401

There is no authenticated member

404

No log entry matches the specified ID

Security

oauth user

PATCH /log-entry/{id}/me

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

Parameters

id Required path string

The LID of the log entry.

Response

200

Success

ReviewRelationshipUpdateResponse
401

There is no authenticated member

403

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

404

No log entry matches the specified ID

Security

oauth user

POST /log-entry/{id}/report

Report a log entry’s review by ID.

Parameters

id Required path string

The LID of the log entry.

Response

204

Success

401

There is no authenticated member

404

No log entry matches the specified ID

GET /log-entry/{id}/statistics

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

Parameters

id Required path string

The LID of the log entry.

Response

200

Success

ReviewStatistics
404

No log entry matches the specified ID

Security

oauth

GET /me

Get details about the authenticated member.

Response

200

Success

MemberAccount
401

There is no authenticated member

Security

oauth user

PATCH /me

Update the profile settings for the authenticated member.

Response

200

Success

MemberSettingsUpdateResponse
400

Bad request

401

There is no authenticated member

GET /me/check-tag

Check whether a tag is being merged before update.

Request

TagCheckRequest

Response

200

Success

204

successful operation

TagCheckResponse
400

Bad request

401

There is no authenticated member

403

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

Security

oauth user

POST /me/collect-item

Collect a hunt item.

Request

CollectRequest

Response

200

Success

401

There is no authenticated member

403

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

DELETE /me/delete-tag

Delete a tag.

Response

204

Success

400

Bad request

401

There is no authenticated member

403

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

POST /me/deregister-push-notifications

Deregister a device so it no longer receives push notifications.

Response

204

Success

401

There is no authenticated member

POST /me/disable

Deactivate account.

Response

204

Success

401

There is no authenticated member

POST /me/register-push-notifications

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

Response

204

Success

401

There is no authenticated member

PATCH /me/update-tag

Update the tag code of a tagging.

Response

200

Success

401

There is no authenticated member

403

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

POST /me/validation-request

Request a validation link via email.

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

Response

204

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

401

There is no authenticated member

403

The authenticated member’s email address was already successfully validated

429

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

Security

oauth user

GET /member/{id}

Get details about a member by ID.

Parameters

id Required path string

The LID of the member.

Response

200

Success

Member
404

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

Security

oauth

GET /member/{id}/activity

A cursored window over the activity for a member.

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

Parameters

id Required path string

The LID of the member.

cursor query string

The pagination cursor.

perPage query integer

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

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

multiple parameters (include=aaa&include=bbb)

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

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

multiple parameters (exclude=aaa&exclude=bbb)

Only supported for paying members.DEPRECATED Use include instead.

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

multiple parameters (where=aaa&where=bbb)

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

adult query boolean

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

Response

200

Success

ActivityResponse
404

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

Security

oauth

GET /member/{id}/list-tags

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

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

Parameters

id Required path string

The LID of the member.

input query string

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

Response

200

Success

TagsResponse
404

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

Security

oauth

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

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

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

Parameters

id Required path string

The LID of the member.

input query string

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

Response

200

Success

MemberTagsResponse
404

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

Security

oauth

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

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

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

Parameters

id Required path string

The LID of the member.

input query string

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

Response

200

Success

MemberTagsResponse
404

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

Security

oauth

GET /member/{id}/me

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

Parameters

id Required path string

The LID of the other member.

Response

200

Success

MemberRelationship
401

There is no authenticated member

404

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

Security

oauth user

PATCH /member/{id}/me

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

Parameters

id Required path string

The LID of the other member.

Response

200

Success

MemberRelationshipUpdateResponse
401

There is no authenticated member

404

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

POST /member/{id}/report

Report a member by ID.

Parameters

id Required path string

The LID of the member.

Response

204

Success

401

There is no authenticated member

404

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

GET /member/{id}/review-tags

DEPRECATED Please use /log-entry-tags

Parameters

id Required path string

The LID of the member.

input query string

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

Response

200

Success

TagsResponse
404

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

Security

oauth

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

DEPRECATED Please use /log-entry-tags instead

Parameters

id Required path string

The LID of the member.

input query string

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

Response

200

Success

MemberTagsResponse
404

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

Security

oauth

GET /member/{id}/statistics

Get statistical data about a member by ID.

Parameters

id Required path string

The LID of the member.

Response

200

Success

MemberStatistics
404

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

Security

oauth

GET /member/{id}/watchlist

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

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

Parameters

id Required path string

The LID of the member.

cursor query string

The pagination cursor.

perPage query integer

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

filmId query
string[]

multiple parameters (filmId=aaa&filmId=bbb)

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

genre query string

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

similarTo query string

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

theme query string

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

minigenre query string

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

nanogenre query string

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

includeGenre query
string[]

multiple parameters (includeGenre=aaa&includeGenre=bbb)

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

excludeGenre query
string[]

multiple parameters (excludeGenre=aaa&excludeGenre=bbb)

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

country query string

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

language query string

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

decade query integer

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

year query integer

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

service query string

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

availabilityType query
string[]

multiple parameters (availabilityType=aaa&availabilityType=bbb)

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

exclusive query boolean

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

unavailable query boolean

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

includeOwned query boolean

Set to true to include films that the user owns.

negate query boolean

Set to true to invert the current service filtering options.

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

multiple parameters (where=aaa&where=bbb)

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

member query string

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

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

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

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

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

tag query string

DEPRECATED Use tagCode instead.

tagCode query string

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

tagger query string

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

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

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

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

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

Response

200

Success

FilmsResponse
403

The specified member’s watchlist is private

404

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

Security

oauth

GET /members

A cursored window over the list of members.

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

Parameters

cursor query string

The pagination cursor.

perPage query integer

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

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

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

member query string

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

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

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

film query string

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

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

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

list query string

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

listRelationship query enum ∈ {Owner, Liked (default), Accessed}

Must be used in conjunction with list. Defaults to Liked, which returns the list of members who have liked the list. Use Accessed to return the list of members who have viewed the shared list. The authenticated member must be the owner of the list in order to use Accessed.

review query string

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

Response

200

Success

MembersResponse

Security

oauth

GET /members/pronouns

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

Response

200

Success

PronounsResponse

Security

oauth

POST /members/register

Create a new account.

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

Request

RegisterRequest

Response

201

Success

Member
400

The username was already taken or is invalid.

Security

oauth

GET /news

Get recent news from the Letterboxd editors.

Parameters

cursor query string

The pagination cursor.

perPage query integer

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

Response

200

Success

NewsResponse

Security

oauth

GET /search

Parameters

cursor query string

The pagination cursor.

perPage query integer

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

input Required query string

The word, partial word or phrase to search for.

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

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

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

multiple parameters (include=aaa&include=bbb)

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

contributionType query enum ∈ {Director, CoDirector, AdditionalDirecting, Actor, Producer, ExecutiveProducer, Writer, OriginalWriter, Casting, Editor, Cinematography, AdditionalPhotography, ProductionDesign, ArtDirection, SetDecoration, SpecialEffects, VisualEffects, Stunts, Choreography, Composer, Songs, Sound, Costumes, MakeUp, Hairstyling, Studio}

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

adult query boolean

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

Response

200

successful operation

SearchResponse

GET /stories

A cursored window over a list of stories.

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

Parameters

cursor query string

The pagination cursor.

perPage query integer

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

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

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

member query string

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

where query
enum[] ∈ {Published, NotPublished}

multiple parameters (where=aaa&where=bbb)

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

Response

200

Success

StoriesResponse
400

Bad request

404

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

Security

oauth

GET /story/{id}

Get details of a story by ID.

Parameters

id Required path string

The LID of the story.

Response

200

Success

Story
404

No story matches the specified ID

Security

oauth

GET /userinfo

Response

default

successful operation

Definitions

AbstractActivity

Properties

type Discriminator

The type of activity.

member MemberSummary

The member associated with the activity.

whenCreated string

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

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

AbstractComment

Properties

type Discriminator
enum[] ∈ {ListComment, ReviewComment}

The type of comment.

id string

The LID of the comment/​reply.

member MemberSummary

The member who posted the comment.

whenCreated string

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

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

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

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

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

removedByAdmin boolean

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

removedByContentOwner boolean

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

deleted boolean

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

blocked boolean

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

blockedByOwner boolean

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

editableWindowExpiresIn integer

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

comment string

The message portion of the comment formatted as HTML.

AbstractSearchItem

Properties

type Discriminator

The type of the search result.

score number

A relevancy value that can be used to order results.

AccessToken

Properties

access_token string

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

token_type string

The type of the access token. Use value: bearer

refresh_token string

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

expires_in integer

The number of seconds before the access token expires.

notBefore integer
issuer string
encodedToken string

ActivityResponse

Properties

next Cursor

The cursor to the next page of results.

items

The list of activity items.

AGoogleBillingSubscription

Properties

subscriptionDaysRemaining integer

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

AListAddition

Properties

list ListIdentifier

The list.

additions integer

The number of films added to the list.

AListEntryOccurrence

Properties

rank integer

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

filmId string

The film LID for this entry.

AListTopic

Properties

name string

The topic name.

items

The list of featured lists for the topic.

AppleIAPSubscription

Properties

subscriptionDaysRemaining integer

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

AppleIAPSubscriptionMessage

Properties

type enum ∈ {Error, Success}

The type of message.

code enum ∈ {SubscriptionAlreadyExpired, SubscriptionBelongsToAnotherMember, UnexpectedError}

The error message code.

title string

The error message text in human-readable form.

AppleIAPSubscriptionRequest

Properties

receiptToken Required string

The receipt token (Base-64 encoded).

AppleIAPSubscriptionResponse

Properties

data Required AppleIAPSubscription

The response object.

messages Required

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

ArticleSearchItem < AbstractSearchItem

Inherited Properties

score Inherited number

A relevancy value that can be used to order results.

Properties

article NewsItem

The article.

AvailabilityTypesResponse

Properties

items

The list of availability types.

CollectRequest

Properties

nonce string
token string
itemId string

CommentCreationRequest

Properties

comment Required string

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

CommentUpdateMessage

Properties

type enum ∈ {Error, Success}

The type of message.

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

The error message code.

title string

The error message text in human-readable form.

CommentUpdateRequest

Properties

comment Required string

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

CommentUpdateResponse

Properties

data Required AbstractComment

The response object.

messages Required

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

ContributionStatistics

Properties

type enum ∈ {Director, CoDirector, AdditionalDirecting, Actor, Producer, ExecutiveProducer, Writer, OriginalWriter, Casting, Editor, Cinematography, AdditionalPhotography, ProductionDesign, ArtDirection, SetDecoration, SpecialEffects, VisualEffects, Stunts, Choreography, Composer, Songs, Sound, Costumes, MakeUp, Hairstyling, Studio}

The type of contribution.

filmCount integer

The number of films for this contribution type.

Contributor

Properties

id string

The LID of the contributor.

name string

The name of the contributor.

tmdbid string

The ID of the contributor on TMDB, if known

statistics ContributorStatistics

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

links

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

huntItems

FIRST PARTY The treasure hunt items related to the contributor.

ContributorSearchItem < AbstractSearchItem

Inherited Properties

score Inherited number

A relevancy value that can be used to order results.

Properties

contributor Contributor

Details of the contributor.

ContributorStatistics

Properties

contributions

The statistics for each contribution type.

ContributorSummary

Properties

id string

The LID of the contributor.

name string

The name of the contributor.

characterName string

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

tmdbid string

The ID of the contributor on TMDB, if known

CountriesResponse

Properties

items

The list of countries.

Country

Properties

key string

The key value of the availability type.

label string

The display name of the availability type.

Cursor

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

DeregisterPushNotificationsRequest

Properties

deviceId Required string

The device ID.

DiaryDetails

Properties

diaryDate string

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

rewatch boolean

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

DiaryEntryActivity < AbstractActivity

Inherited Properties

member Inherited MemberSummary

The member associated with the activity.

whenCreated Inherited string

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

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

Properties

diaryEntry LogEntry

The log entry associated with this activity

DisableAccountRequest

Properties

currentPassword Required string

The member’s current password.

mode enum ∈ {Disable, Delete}

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

Film

Properties

id string

The LID of the film.

name string

The title of the film.

originalName string

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

sortingName string

A modified version of the name that has been normalized for consistent sorting.

alternativeNames
string[]

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

releaseYear integer

The year in which the film was first released.

directors

The list of directors for the film.

poster Image

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

adultPoster Image

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

top250Position integer

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

adult boolean

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

reviewsHidden boolean

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

filmCollectionId string

The LID of the collection containing this film.

links

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

relationships

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

genres

The film’s genres.

tagline string

The tagline for the film.

description