Overview

The Letterboxd API provides access to data on the Letterboxd.com website.

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.
For films, lists and reviews, the LID can also be found through the Letterboxd website as the path portion of the entity’s shareable boxd.it URL.
Member LIDs are included in the response headers of an HTTP request for the member’s profile page (as x-letterboxd-identifier) and can also be found via the shareable boxd.it URL of the member’s profile in our iOS app.

In all cases the response from an endpoint will be a JSON object, with HTTP status codes indicating successful results and error states.

Authentication

The Letterboxd API uses standard OAuth 2Resource Owner and Refresh Token authorization flows to grant access to an authenticated member via an access token, which may be refreshed at regular intervals to keep the member signed in.
When generating or refreshing an access token, make a form request to the /auth/token endpoint with Content-Type: application/x-www-form-urlencoded and Accept: application/json headers, and request body parameters as follows:

Generate a token

grant_type Required

string

Use value: password

username Required

string

The member’s username or email address.

password Required

string

The member’s password.

Refresh a token

grant_type Required

string

Use value: refresh_token

refresh_token Required

string

Your current refresh token value for the member.

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

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

Request signing

All API requests must be signed in the following way:

Create a salted string of the form [METHOD]\u0000[URL]\u0000[BODY], where [METHOD] is GET, POST, etc.,
[URL] is the fully-qualified request URL including the apikey, nonce, timestamp
and any other method parameters, and [BODY] is a JSON-encoded string (for POST, PATCH and DELETE requests) or empty
(for GET requests). Next, create a [SIGNATURE] from the salted string by applying a lower-case HMAC/SHA-256
transformation, using your API Secret, and append it to your API request [URL] as the final query parameter:
…&signature=[SIGNATURE] (the resulting request [URL] should contain
at least apikey, nonce, timestamp and signature parameters).

Notes: you must specify a Content-Type: application/json request header if [BODY] is JSON-encoded.
\u0000 is the unicode representation of the null byte (please ensure this character is represented according to
the conventions of your platform or framework, rather than including the literal string "\u0000"). The apikey
parameter is your supplied API Key. The nonce parameter should be a UUID string and must be unique for each API request.
The timestamp parameter is the number of seconds since Jan 1, 1970 (UTC).

Endpoints

POST /auth/forgotten-password-request

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

Response

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

Request

Response

POST /me/validation-request

Request a validation link via email.

Calls to this endpoint must include the access token for an authenticated member (see Authentication). If the email address associated with a member’s account has not been validated and the validation link has expired or been lost, use this endpoint to request a new validation link.

GET /member/{id}/statistics

Parameters

Response

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

GET /member/{id}/watchlist

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

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

Request

Response

GET /members/pronouns

Response

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.

AccessToken

Properties

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

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.

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

Properties

CommentsRequest

Properties

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

sort

enum
∈
{Date, 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.

The backdrop’s vertical focal point, expressed as a proportion of the image’s height, using values between 0.0 and 1.0. Use when cropping the image into a shorter space, such as in the page for a film on the Letterboxd site.

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 FilmPopularityWithFriends values are only available to signed-in members and consider popularity amongst the signed-in member’s friends.The AuthenticatedMemberRating 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).

genre

string

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

decade

integer

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

1990

year

integer

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

1994

service

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.

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=MemberRatingHighToLow or sort=MemberRatingLowToHigh

includeFriends

enum
∈
{None, 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.

tagCode

string

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

tagger

string

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

includeTaggerFriends

enum
∈
{None, 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.

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 FilmPopularityWithFriends values are only available to signed-in members and consider popularity amongst the signed-in member’s friends.The AuthenticatedMemberRating 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 RatingHighToLow and RatingLowToHigh options are deprecated in favor of AverageRatingHighToLow and AverageRatingLowToHigh.

filmId

string[]

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

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=MemberRatingHighToLow or sort=MemberRatingLowToHigh

includeFriends

enum
∈
{None, 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

string

DEPRECATED Use tagCode instead.

tagCode

string

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

tagger

string

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

includeTaggerFriends

enum
∈
{None, 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.

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

rating

number

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

FilmRelationship

Properties

watched

boolean

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

whenWatched

string

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

liked

boolean

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

whenLiked

string

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

favorited

boolean

Will be true if the member listed the film as one of their four favorites.

inWatchlist

boolean

Will be true if the film is in the member’s watchlist.

whenAddedToWatchlist

string

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

whenCompletedInWatchlist

string

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

rating

number

The member’s rating for the film.

reviews

string[]

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

diaryEntries

string[]

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

FilmRelationshipUpdateMessage

Properties

type

enum
∈
{Error, Success}

The type of message.

code

enum
∈
{InvalidRatingValue, UnableToRemoveWatch}

The error message code.

title

string

The error message text in human-readable form.

FilmRelationshipUpdateRequest

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

Properties

watched

boolean

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

liked

boolean

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

inWatchlist

boolean

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

rating

number

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

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 FilmPopularityWithFriends values are only available to signed-in members and consider popularity amongst the signed-in member’s friends.The AuthenticatedMemberRating 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 RatingHighToLow and RatingLowToHigh options are deprecated in favor of AverageRatingHighToLow and AverageRatingLowToHigh.

filmId

string[]

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

filmId=b8wK&filmId=imdb:tt1396484

genre

string

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

decade

integer

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

1990

year

integer

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

1994

service

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.

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=MemberRatingHighToLow or sort=MemberRatingLowToHigh

includeFriends

enum
∈
{None, 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

string

DEPRECATED Use tagCode instead.

tagCode

string

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

tagger

string

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

includeTaggerFriends

enum
∈
{None, 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.

ListCommentsResponse

Properties

ListCreateEntry

Properties

film
Required

string

The LID of the film.

rank

integer

If the list is ranked, this is the entry’s rank in the list, numbered from 1. If not set, the entry will be appended to the end of the list. Sending two or more ListCreateEntrys with the same rank will return an error.

notes

string

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

containsSpoilers

boolean

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

The order in which the entries should be returned. Defaults to ListRanking, which is the order specified by the list owner.The AuthenticatedMemberRating 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 RatingHighToLow and RatingLowToHigh options are deprecated in favor of AverageRatingHighToLow and AverageRatingLowToHigh.

filmId

string[]

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

filmId=b8wK&filmId=imdb:tt1396484

genre

string

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

decade

integer

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

1990

year

integer

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

1994

service

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.

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=MemberRatingHighToLow or sort=MemberRatingLowToHigh

includeFriends

enum
∈
{None, 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

string

DEPRECATED Use tagCode instead.

tagCode

string

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

tagger

string

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

includeTaggerFriends

enum
∈
{None, 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.

ListRelationship

Properties

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

subscribed

boolean

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

subscriptionState

enum
∈
{Subscribed, NotSubscribed, Unsubscribed}

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

commentThreadState

enum
∈
{CanComment, Banned, Blocked, NotCommentable}

The authenticated member’s state with respect to adding comments for this list.CanComment means the authenticated member is authorized to add a comment. All other values mean the authenticated member is not authorized to add a comment.Banned means the Letterboxd community managers have restricted the member’s ability to comment on the site.Blocked means the owner has blocked the member from adding comments.NotCommentable means that it is invalid to try to add comments to this content.

ListRelationshipUpdateRequest

Properties

liked

boolean

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

subscribed

boolean

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