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.

Authentication

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

Generate a token

grant_type Required string Use value: password
username Required string The member’s username or email address.
password Required string The member’s password.

Refresh a token

grant_type Required string Use value: refresh_token
refresh_token Required string Your current refresh token value for the member.

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

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

Request signing

All API requests must be signed in the following way:

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

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

Endpoints

POST /apple-iap/subscription

Process an Apple In-app Purchase receipt.

Request

AppleIAPSubscriptionRequest

Response

200 Success
AppleIAPSubscriptionResponse
401 There is no authenticated member

POST /auth/forgotten-password-request

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

Request

ForgottenPasswordRequest

Response

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

GET /auth/get-login-token

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

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

Response

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

POST /auth/revoke

Response

default successful operation

POST /auth/token

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

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

Response

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

GET /auth/username-check

Check if a username is available to register.

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

Parameters

username Required string query The username to check.

Response

200 Success
UsernameCheckResponse

DELETE /comment/{id}

Delete a comment.

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

Parameters

id Required string path The LID of the comment/reply.

Response

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

PATCH /comment/{id}

Update the message portion of a comment.

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

Request

CommentUpdateRequest

Parameters

id Required string path The LID of the comment/reply.

Response

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

POST /comment/{id}/report

Report a comment by ID.

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

Request

ReportCommentRequest

Parameters

id Required string path 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 string path The LID of the contributor.

Response

200 Success
Contributor
404 No contributor matches the specified ID

GET /contributor/{id}/contributions

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

Use the ‘next’ cursor to move through the list

Request

FilmContributionsRequest

Parameters

id Required string path The LID of the contributor.

Response

200 Success
FilmContributionsResponse
404 No contributor matches the specified ID

GET /film-collection/{id}

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

Request

FilmCollectionRequest

Parameters

id Required string path The LID of the film collection.

Response

200 Success
FilmCollection
404 No film collection matches the specified ID

GET /film/{id}

Get details about a film by ID.

Parameters

id Required string path The LID of the film.

Response

200 Success
Film
404 No film matches the specified ID

GET /film/{id}/availability

Get availability data for a film by ID. Only available to first-party API clients.

Parameters

id Required string path The LID of the film.

Response

200 Success
FilmAvailabilityResponse
404 No film matches the specified ID

GET /film/{id}/me

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

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

Parameters

id Required string path The LID of the film.

Response

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

PATCH /film/{id}/me

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

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

Request

FilmRelationshipUpdateRequest

Parameters

id Required string path 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.

Request

MemberFilmRelationshipsRequest

Parameters

id Required string path The LID of the film.

Response

200 Success
MemberFilmRelationshipsResponse
404 No film matches the specified ID

POST /film/{id}/report

Report a film by ID.

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

Request

ReportFilmRequest

Parameters

id Required string path 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 string path The LID of the film.

Response

200 Success
FilmStatistics
404 No film matches the specified ID

GET /films

A cursored window over the list of films.

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

Request

FilmsRequest

Response

200 Success
FilmsResponse

GET /films/autocomplete

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

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

Request

FilmAutocompleteRequest

Response

200 Success
FilmsAutocompleteResponse

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

GET /films/genres

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

Genres are returned in alphabetical order.

Response

200 Success
GenresResponse

DELETE /list/{id}

Delete a list by ID.

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

Parameters

id Required string path 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 string path The LID of the list.

Response

200 Success
List
404 No list matches the specified ID

PATCH /list/{id}

Update a list by ID.

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

Request

ListUpdateRequest

Parameters

id Required string path 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.

Request

CommentsRequest

Parameters

id Required string path The LID of the list.

Response

200 Success
ListCommentsResponse
404 No list matches the specified ID

POST /list/{id}/comments

Create a comment on a list.

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

Request

CommentCreationRequest

Parameters

id Required string path 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.

Request

ListEntriesRequest

Parameters

id Required string path The LID of the list.

Response

200 Success
ListEntriesResponse
404 No list matches the specified ID

GET /list/{id}/me

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

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

Parameters

id Required string path The LID of the list.

Response

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

PATCH /list/{id}/me

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

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

Request

ListRelationshipUpdateRequest

Parameters

id Required string path The LID of the list.

Response

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

POST /list/{id}/report

Report a list by ID.

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

Request

ReportListRequest

Parameters

id Required string path 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 string path The LID of the list.

Response

200 Success
ListStatistics
404 No list matches the specified ID

GET /lists

A cursored window over a list of lists.

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

Request

ListsRequest

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.

POST /lists

Create a list.

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

Request

ListCreationRequest

Response

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

GET /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.

Request

LogEntriesRequest

Response

200 Success
LogEntriesResponse
404 Film or Member not found

POST /log-entries

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

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

Request

LogEntryCreationRequest

Response

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

DELETE /log-entry/{id}

Delete a log entry by ID.

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

Parameters

id Required string path 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 string path The LID of the log entry.

Response

200 Success
LogEntry
404 No log entry matches the specified ID

PATCH /log-entry/{id}

Update a log entry by ID.

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

Request

LogEntryUpdateRequest

Parameters

id Required string path 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.

Request

CommentsRequest

Parameters

id Required string path The LID of the log entry.

Response

200 Success
ReviewCommentsResponse
404 No log entry matches the specified ID

POST /log-entry/{id}/comments

Create a comment on a review.

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

Request

CommentCreationRequest

Parameters

id Required string path The LID of the log entry.

Response

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

GET /log-entry/{id}/me

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

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

Parameters

id Required string path The LID of the log entry.

Response

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

PATCH /log-entry/{id}/me

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

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

Request

ReviewRelationshipUpdateRequest

Parameters

id Required string path The LID of the log entry.

Response

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

POST /log-entry/{id}/report

Report a log entry’s review by ID.

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

Request

ReportReviewRequest

Parameters

id Required string path 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 string path The LID of the log entry.

Response

200 Success
ReviewStatistics
404 No log entry matches the specified ID

GET /me

Get details about the authenticated member.

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

Response

200 Success
MemberAccount
401 There is no authenticated member

PATCH /me

Update the profile settings for the authenticated member.

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

Request

MemberSettingsUpdateRequest

Response

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

POST /me/deregister-push-notifications

Deregister a device so it no longer receives push notifications.

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

Request

DeregisterPushNotificationsRequest

Response

204 Success
401 There is no authenticated member

POST /me/register-push-notifications

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

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

Request

RegisterPushNotificationsRequest

Response

204 Success
401 There is no authenticated member

POST /me/validation-request

Request a validation link via email.

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

Response

204 Success (the email was dispatched if it matched an existing account)
401 There is no authenticated member
403 The authenticated member’s email address was already successfully validated
429 Too many validation requests have been made (the email is probably in the member’s spam or junk folder)

GET /member/{id}

Get details about a member by ID.

Parameters

id Required string path The LID of the member.

Response

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

GET /member/{id}/activity

A cursored window over the activity for a member.

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

Request

ActivityRequest

Parameters

id Required string path The LID of the member.

Response

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

GET /member/{id}/list-tags

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

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

Request

MemberTagsRequest

Parameters

id Required string path The LID of the member.

Response

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

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

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

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

Request

MemberTagsRequest

Parameters

id Required string path The LID of the member.

Response

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

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

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

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

Request

MemberTagsRequest

Parameters

id Required string path The LID of the member.

Response

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

GET /member/{id}/me

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

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

Parameters

id Required string path The LID of the other member.

Response

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

PATCH /member/{id}/me

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

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

Request

MemberRelationshipUpdateRequest

Parameters

id Required string path The LID of the other member.

Response

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

POST /member/{id}/report

Report a member by ID.

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

Request

ReportMemberRequest

Parameters

id Required string path 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

Request

MemberTagsRequest

Parameters

id Required string path The LID of the member.

Response

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

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

DEPRECATED Please use /log-entry-tags instead

Request

MemberTagsRequest

Parameters

id Required string path The LID of the member.

Response

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

GET /member/{id}/statistics

Get statistical data about a member by ID.

Parameters

id Required string path The LID of the member.

Response

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

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

WatchlistRequest

Parameters

id Required string path The LID of the member.

Response

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

GET /members

A cursored window over the list of members.

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

Request

MembersRequest

Response

200 Success
MembersResponse

GET /members/pronouns

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

Response

200 Success
PronounsResponse

POST /members/register

Create a new account.

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

Request

RegisterRequest

Response

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

GET /news

Get recent news from the Letterboxd editors.

Request

NewsRequest

Response

200 Success
NewsResponse

GET /search

Request

SearchRequest

Response

200 successful operation
SearchResponse

Definitions

AbstractActivity

Properties

type Discriminator
enum[] ∈ {DiaryEntryActivity, FilmLikeActivity, FilmRatingActivity, FilmWatchActivity, FollowActivity, InvitationAcceptedActivity, ListActivity, ListCommentActivity, ListLikeActivity, RegistrationActivity, ReviewActivity, ReviewCommentActivity, ReviewLikeActivity, WatchlistActivity}
The type of activity.
member MemberSummary The member associated with the activity.
whenCreated string The timestamp of the activity, in ISO 8601 format with UTC timezone, i.e. YYYY-MM-DDThh:mm:ssZ 
"1997-08-29T07:14:00Z"

AbstractComment

Properties

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

AbstractSearchItem

Properties

type Discriminator
enum[] ∈ {ContributorSearchItem, FilmSearchItem, ListSearchItem, MemberSearchItem, ReviewSearchItem, TagSearchItem}
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.
issuer string

ActivityRequest

Properties

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

ActivityResponse

Properties

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

AppleIAPSubscription

Properties

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

AppleIAPSubscriptionMessage

Properties

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

AppleIAPSubscriptionRequest

Properties

receiptToken Required string The receipt token (Base-64 encoded).

AppleIAPSubscriptionResponse

Properties

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

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
CommentUpdateMessage[]
 		A list of messages the API client should show to the user.

CommentsRequest

Properties

cursor Cursor The pagination cursor.
perPage integer The number of items to include per page (default is 20, maximum is 100).
sort 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 boolean Use this to discover any comments that were deleted.

ContributionStatistics

Properties

type enum ∈ {Director, CoDirector, Actor, Producer, Writer, Editor, Cinematography, ProductionDesign, ArtDirection, SetDecoration, VisualEffects, Composer, Sound, Costumes, MakeUp, 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.
statistics ContributorStatistics An array of the types of contributions made, with a count of films for each contribution type.
links
Link[]
 		A list of relevant URLs for this entity, on Letterboxd and external sites.

ContributorSearchItem < AbstractSearchItem

Inherited Properties

score Inherited number A relevancy value that can be used to order results.

Properties

score number A relevancy value that can be used to order results.
contributor Contributor Details of the contributor.

ContributorStatistics

Properties

contributions
ContributionStatistics[]
 		The statistics for each contribution type.

ContributorSummary

Properties

id string The LID of the contributor.
name string The name of the contributor.
characterName string The character name if available (only if the contribution is as an Actor; see the type field in FilmContributions).

Country

Properties

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

Cursor

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

DeregisterPushNotificationsRequest

Properties

deviceId Required string The device ID.

DiaryDetails

Properties

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

DiaryEntryActivity < AbstractActivity

Inherited Properties

member Inherited MemberSummary The member associated with the activity.
whenCreated Inherited string The timestamp of the activity, in ISO 8601 format with UTC timezone, i.e. YYYY-MM-DDThh:mm:ssZ 
"1997-08-29T07:14:00Z"

Properties

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"
diaryEntry LogEntry The log entry associated with this activity

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.
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.
tagline string The tagline for the film.
description string A synopsis of the film.
runTime integer The film’s duration (in minutes).
poster Image The film’s poster image (2:3 aspect ratio in multiple sizes).
backdrop Image The film’s backdrop image (16:9 ratio in multiple sizes).
backdropFocalPoint number The backdrop’s vertical focal point, expressed as a proportion of the image’s height, using values between 0.0 and 1.0. Use when cropping the image into a shorter space, such as in the page for a film on the Letterboxd site.
trailer FilmTrailer The film’s trailer.
genres
Genre[]
 		The film’s genres.
countries
Country[]
 		The film’s production countries.
languages
Language[]
 		The film’s spoken languages.
contributions
FilmContributions[]
 		The film’s contributors (director, cast and crew) grouped by discipline.
filmCollectionId string The LID of the collection containing this film.
news
NewsItem[]
 		The related news items for the film.
links
Link[]
 		A list of relevant URLs for this entity, on Letterboxd and external sites.

FilmAutocompleteRequest

Properties

perPage integer The number of items to include per page (default is 20, maximum is 100).
input Required string The word, partial word or phrase to match against.

FilmAvailability

Properties

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

FilmAvailabilityResponse

Properties

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

FilmCollection

Properties

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

FilmCollectionRequest

Properties

sort enum ∈ {FilmName, ReleaseDateLatestFirst, ReleaseDateEarliestFirst, AuthenticatedMemberRatingHighToLow, AuthenticatedMemberRatingLowToHigh, MemberRatingHighToLow, MemberRatingLowToHigh, AverageRatingHighToLow, AverageRatingLowToHigh, FilmDurationShortestFirst, FilmDurationLongestFirst, FilmPopularity, 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 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.
where
enum[] ∈ {Released, NotReleased, InWatchlist, NotInWatchlist, WatchedFromWatchlist, Watched, NotWatched, FeatureLength, NotFeatureLength}
Specify one or more values to limit the list of films accordingly. 
where=Watched&where=Released
member string Specify the LID of a member to limit the returned films according to the value set in memberRelationship or to access the MemberRatingHighToLow and MemberRatingLowToHigh sort options.
memberRelationship enum ∈ {Ignore, Watched, NotWatched, Liked, NotLiked, 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=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.

FilmContribution

Properties

type enum ∈ {Director, CoDirector, Actor, Producer, Writer, Editor, Cinematography, ProductionDesign, ArtDirection, SetDecoration, VisualEffects, Composer, Sound, Costumes, MakeUp, Studio} The type of contribution.
film FilmSummary The film.
characterName string The name of the character (only when type is Actor).

FilmContributions

Properties

type enum ∈ {Director, CoDirector, Actor, Producer, Writer, Editor, Cinematography, ProductionDesign, ArtDirection, SetDecoration, VisualEffects, Composer, Sound, Costumes, MakeUp, Studio} The type of contribution.
contributors
ContributorSummary[]
 		The list of contributors of the specified type for the film.

FilmContributionsCollection

Properties

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

FilmContributionsRequest

Properties

cursor Cursor The pagination cursor.
perPage integer The number of items to include per page (default is 20, maximum is 100).
sort enum ∈ {FilmName, ReleaseDateLatestFirst, ReleaseDateEarliestFirst, AuthenticatedMemberRatingHighToLow, AuthenticatedMemberRatingLowToHigh, MemberRatingHighToLow, MemberRatingLowToHigh, AverageRatingHighToLow, AverageRatingLowToHigh, RatingHighToLow, RatingLowToHigh, FilmDurationShortestFirst, FilmDurationLongestFirst, FilmPopularity, 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 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
type enum ∈ {Director, CoDirector, Actor, Producer, Writer, Editor, Cinematography, ProductionDesign, ArtDirection, SetDecoration, VisualEffects, Composer, Sound, Costumes, MakeUp, Studio} The type of contribution.
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.
where
enum[] ∈ {Released, NotReleased, InWatchlist, NotInWatchlist, WatchedFromWatchlist, Watched, NotWatched, FeatureLength, NotFeatureLength}
Specify one or more values to limit the list of films accordingly. 
where=Watched&where=Released
member string Specify the LID of a member to limit the returned films according to the value set in memberRelationship or to access the MemberRatingHighToLow and MemberRatingLowToHigh sort options.
memberRelationship enum ∈ {Ignore, Watched, NotWatched, Liked, NotLiked, 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=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.

FilmContributionsResponse

Properties

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

FilmContributorMemberRelationship

Properties

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

FilmContributorMetadata

Properties

type enum ∈ {Director, CoDirector, Actor, Producer, Writer, Editor, Cinematography, ProductionDesign, ArtDirection, SetDecoration, VisualEffects, Composer, Sound, Costumes, MakeUp, Studio} The type of contribution.
data FilmsMetadata The details for this contribution type.

FilmContributorRelationship

Properties

type enum ∈ {Director, CoDirector, Actor, Producer, Writer, Editor, Cinematography, ProductionDesign, ArtDirection, SetDecoration, VisualEffects, Composer, Sound, Costumes, MakeUp, Studio} The type of contribution.
relationship FilmsRelationship The relationship the member has with the (filtered) films.

FilmIdentifier

Properties

id string The LID of the film.

FilmLikeActivity < AbstractActivity

Inherited Properties

member Inherited MemberSummary The member associated with the activity.
whenCreated Inherited string The timestamp of the activity, in ISO 8601 format with UTC timezone, i.e. YYYY-MM-DDThh:mm:ssZ 
"1997-08-29T07:14:00Z"

Properties

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"
film FilmSummary The film associated with the activity. Includes a MemberFilmRelationship for the member who added the activity.

FilmRatingActivity < AbstractActivity

Inherited Properties

member Inherited MemberSummary 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

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"
film FilmSummary The film associated with the activity. Includes a MemberFilmRelationship for the member who added the activity.
rating number The member’s rating for the film. Allowable values are between 0.5 and 5.0, with increments of 0.5.

FilmRelationship

Properties

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

FilmRelationshipUpdateResponse

Properties

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

FilmSearchItem < AbstractSearchItem

Inherited Properties

score Inherited number A relevancy value that can be used to order results.

Properties

score number A relevancy value that can be used to order results.
film FilmSummary The film returned by the search.

FilmServicesResponse

Properties

items
Service[]
 		The list of film services.

FilmStatistics

Properties

film FilmIdentifier The film for which statistics were requested.
counts FilmStatisticsCounts The number of watches, ratings, likes, etc. for the film.
rating number The weighted average rating of the film between 0.5 and 5.0. Will not be present if the film has not received sufficient ratings.
ratingsHistogram
RatingsHistogramBar[]
 		A summary of the number of ratings at each increment between 0.5 and 5.0.

FilmStatisticsCounts

Properties

watches integer The number of members who have watched the film.
likes integer The number of members who have liked the film.
ratings integer The number of members who have rated the film.
fans integer The number of members who have the film as one of their four favorites.
lists integer The number of lists in which the film appears.
reviews integer The number of reviews for the film.

FilmSummary

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.
alternativeNames
string[]
 		The other names by which the film is known (including alternative titles and/or foreign translations).
releaseYear integer The year in which the film was first released.
directors
ContributorSummary[]
 		The list of directors for the film.
poster Image The film’s poster image (2:3 aspect ratio in multiple sizes).
filmCollectionId string The LID of the collection containing this film.
links
Link[]
 		A list of relevant URLs for this entity, on Letterboxd and external sites.
relationships
MemberFilmRelationship[]
 		Relationships to the film for the authenticated member (if any) and other members where relevant.

FilmTrailer

Properties

id string The YouTube ID of the trailer. 
"ICp4g9p_rgo"
url string The YouTube URL for the trailer. 
"https://www.youtube.com/watch?v=ICp4g9p_rgo"

FilmWatchActivity < 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

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"
film FilmSummary The film associated with the activity. Includes a MemberFilmRelationship for the member who added the activity.

FilmsAutocompleteResponse

Properties

items
FilmSummary[]
 		The list of films.

FilmsMemberRelationship

Properties

member MemberSummary The member.
relationship FilmsRelationship The relationship details.

FilmsMetadata

Properties

totalFilmCount integer The total number of films.
filteredFilmCount integer The number of films that match the filter for this request.

FilmsRelationship

Properties

counts FilmsRelationshipCounts The number of watches and likes for the films.

FilmsRelationshipCounts

Properties

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

FilmsRequest

Properties

cursor Cursor The pagination cursor.
perPage integer The number of items to include per page (default is 20, maximum is 100).
sort enum ∈ {FilmName, ReleaseDateLatestFirst, ReleaseDateEarliestFirst, AuthenticatedMemberRatingHighToLow, AuthenticatedMemberRatingLowToHigh, MemberRatingHighToLow, MemberRatingLowToHigh, AverageRatingHighToLow, AverageRatingLowToHigh, RatingHighToLow, RatingLowToHigh, FilmDurationShortestFirst, FilmDurationLongestFirst, FilmPopularity, 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 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.
where
enum[] ∈ {Released, NotReleased, InWatchlist, NotInWatchlist, WatchedFromWatchlist, Watched, NotWatched, FeatureLength, NotFeatureLength}
Specify one or more values to limit the list of films accordingly. 
where=Watched&where=Released
member string Specify the LID of a member to limit the returned films according to the value set in memberRelationship or to access the MemberRatingHighToLow and MemberRatingLowToHigh sort options.
memberRelationship enum ∈ {Ignore, Watched, NotWatched, Liked, NotLiked, 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=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.

FilmsResponse

Properties

next Cursor The cursor to the next page of results.
items
FilmSummary[]
 		The list of films.

FollowActivity < 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

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"
followed MemberSummary A summary of the member that was followed.

ForgottenPasswordRequest

Properties

emailAddress string

Genre

Properties

id string The LID of the genre.
name string The name of the genre.

GenresResponse

Properties

items
Genre[]
 		The list of genres.

Image

Properties

sizes
ImageSize[]
 		The available sizes for the image.

ImageSize

Properties

width integer The image width in pixels.
height integer The image height in pixels.
url string The URL to the image file.

InvitationAcceptedActivity < 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

type InvitationAcceptedActivity
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"
invitor MemberSummary

Language

Properties

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

Link

Properties

type enum ∈ {letterboxd, tmdb, imdb, gwi, justwatch} Denotes which site the link is for.
id string The object ID for the linked entity on the destination site.
url string The fully qualified URL on the destination site.

Links

Properties

links
Link[]
 		A link to the member’s profile page on the Letterboxd website.

List

Properties

id string The LID of the list.
name string The name of the list.
filmCount integer The number of films in the list.
published boolean Will be true if the owner has elected to publish the list for other members to see.
ranked boolean Will be true if the owner has elected to make this a ranked list.
hasEntriesWithNotes boolean Will be true if the owner has added notes to any entries.
descriptionLbml string The list description in LBML. May contain the following HTML tags: <br> <strong> <em> <b> <i> <a href=""> <blockquote>.
tags
string[]
 		DEPRECATED Use tags2 instead.
tags2
Tag[]
 		The tags for the list.
canShareOn
enum[] ∈ {Facebook}
The third-party service or services to which this list can be shared. Only included if the authenticated member is the list’s owner.DEPRECATED No longer supported by Facebook.
sharedOn
enum[] ∈ {Facebook}
The third-party service or services to which this list has been shared. Only included if the authenticated member is the list’s owner.DEPRECATED No longer supported by Facebook.
whenCreated string ISO 8601 format with UTC timezone, i.e. YYYY-MM-DDThh:mm:ssZ 
"1997-08-29T07:14:00Z"
whenPublished string ISO 8601 format with UTC timezone, i.e. YYYY-MM-DDThh:mm:ssZ 
"1997-08-29T07:14:00Z"
commentPolicy enum ∈ {Anyone, Friends, You} The policy determining who can post comments to the list. You in this context refers to the content owner. Use the commentThreadState property of the ListRelationship to determine the signed-in member’s ability to comment (or not).
owner MemberSummary The member who owns the list.
clonedFrom ListIdentifier The list this was cloned from, if applicable.
previewEntries
ListEntrySummary[]
 		The first 12 entries in the list. To fetch more than 12 entries, and to fetch the entry notes, use the /list/{id}/entries endpoint.
links
Link[]
 		A list of relevant URLs for this entity, on Letterboxd and external sites.
description string The list description formatted as HTML.

ListActivity < 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

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"
list ListSummary The list associated with the activity.
clonedFrom ListSummary The list that was cloned, if applicable

ListComment < AbstractComment

Inherited Properties

id Inherited string The LID of the comment/reply.
member Inherited MemberSummary The member who posted the comment.
whenCreated Inherited string ISO 8601 format with UTC timezone, i.e. YYYY-MM-DDThh:mm:ssZ 
"1997-08-29T07:14:00Z"
whenUpdated Inherited string ISO 8601 format with UTC timezone, i.e. YYYY-MM-DDThh:mm:ssZ 
"1997-08-29T07:14:00Z"
commentLbml Inherited string The message portion of the comment in LBML. May contain the following HTML tags: <br> <strong> <em> <b> <i> <a href=""> <blockquote>.
removedByAdmin Inherited boolean If Letterboxd moderators have removed the comment from the site, removedByAdmin will be true and comment will not be included.
removedByContentOwner Inherited boolean If the content owner has removed the comment from the site, removedByContentOwner will be true and comment will not be included.
deleted Inherited boolean If the comment owner has removed the comment from the site, deleted will be true and comment will not be included.
blocked Inherited boolean If the authenticated member has blocked the commenter, blocked will be true and comment will not be included.
blockedByOwner Inherited boolean If the content owner has blocked the commenter, blockedByOwner will be true and comment will not be included.
editableWindowExpiresIn Inherited 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 Inherited string The message portion of the comment formatted as HTML.

Properties

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 list 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.
list ListIdentifier The list on which the comment was posted.
comment string The message portion of the comment formatted as HTML.

ListCommentActivity < 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

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"
list ListSummary The list associated with the activity.
comment ListComment The comment associated with the activity.

ListCommentsResponse

Properties

next Cursor The cursor to the next page of results.
items
ListComment[]
 		The list of comments.

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.

ListCreateMessage

Properties

type enum ∈ {Error, Success} The type of message.
code enum ∈ {ListNameIsBlank, UnknownFilmCode, InvalidRatingValue, DuplicateRank, EmptyPublicList, CloneSourceNotFound, SharingServiceNotAuthorized, CannotSharePrivateList, ListDescriptionIsTooLong, ListEntryNotesTooLong} The error message code.
title string The error message text in human-readable form.

ListCreateResponse

Properties

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

ListCreationRequest

Properties

published Required boolean Set to true if the owner has elected to publish the list for other members to see.
name Required string The name of the list.
commentPolicy enum ∈ {Anyone, Friends, You} The policy determining who can post comments to the list. You in this context refers to the content owner. Use the commentThreadState property of the ListRelationship to determine the signed-in member’s ability to comment (or not).
ranked Required boolean Set to true if the owner has elected to make this a ranked list.
description string The list description in LBML. May contain the following HTML tags: <br> <strong> <em> <b> <i> <a href=""> <blockquote>. This field has a maximum size of 100,000 characters.
clonedFrom string The LID of a list to clone from. Only supported for paying members.
tags
string[]
 		The tags for the list.
entries
ListCreateEntry[]
 		The films that comprise the list. Required unless source is set.
share
enum[] ∈ {Facebook}
The third-party service or services to which this list should be shared. Valid options are found in the MemberAccount.authorizedSharingServicesForLists (see the /me endpoint).DEPRECATED No longer supported by Facebook.

ListEntriesRequest

Properties

cursor Cursor The pagination cursor.
perPage integer The number of items to include per page (default is 20, maximum is 100).
sort enum ∈ {ListRanking, WhenAddedToList, FilmName, OwnerRatingHighToLow, OwnerRatingLowToHigh, AuthenticatedMemberRatingHighToLow, AuthenticatedMemberRatingLowToHigh, MemberRatingHighToLow, MemberRatingLowToHigh, AverageRatingHighToLow, AverageRatingLowToHigh, RatingHighToLow, RatingLowToHigh, ReleaseDateLatestFirst, ReleaseDateEarliestFirst, FilmDurationShortestFirst, FilmDurationLongestFirst, FilmPopularity, FilmPopularityThisWeek, FilmPopularityThisMonth, FilmPopularityThisYear} The order in which the entries should be returned. Defaults to ListRanking, which is the order specified by the list owner.The 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.
where
enum[] ∈ {Released, NotReleased, InWatchlist, NotInWatchlist, WatchedFromWatchlist, Watched, NotWatched, FeatureLength, NotFeatureLength}
Specify one or more values to limit the list of films accordingly. 
where=Watched&where=Released
member string Specify the LID of a member to limit the returned films according to the value set in memberRelationship or to access the MemberRatingHighToLow and MemberRatingLowToHigh sort options.
memberRelationship enum ∈ {Ignore, Watched, NotWatched, Liked, NotLiked, 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=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.

ListEntriesResponse

Properties

next Cursor The cursor to the next page of results.
items
ListEntry[]
 		The list of entries.
metadata FilmsMetadata The filtered and total count of films in the list.
relationships
FilmsMemberRelationship[]
 		The relationships to the films in the list for the members referenced in the request.

ListEntry

Properties

rank integer If the list is ranked, this is the entry’s rank in the list, numbered from 1.
notesLbml 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 Will be true if the member has indicated that the notes field contains plot spoilers for the film.
film FilmSummary The film for this entry. Includes a MemberFilmRelationship for the member who created the list.
notes string The notes for the list entry formatted as HTML.

ListEntrySummary

Properties

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

ListIdentifier

Properties

id string The LID of the list.

ListLikeActivity < 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

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"
list ListSummary The list associated with the activity.

ListRelationship

Properties

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

ListRelationshipUpdateMessage

Properties

type enum ∈ {Error, Success} The type of message.
code enum ∈ {LikeBlockedContent, LikeOwnList, SubscribeWhenOptedOut, SubscribeToContentYouBlocked, SubscribeToBlockedContent} The error message code.
title string The error message text in human-readable form.

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.

ListRelationshipUpdateResponse

Properties

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

ListSearchItem < AbstractSearchItem

Inherited Properties

score Inherited number A relevancy value that can be used to order results.

Properties

score number A relevancy value that can be used to order results.
list ListSummary The list.

ListStatistics

Properties

list ListIdentifier The list for which statistics were requested.
counts ListStatisticsCounts The number of comments and likes for the list.

ListStatisticsCounts

Properties

comments integer The number of comments for the list.
likes integer The number of members who like the list.

ListSummary

Properties

id string The LID of the list.
name string The name of the list.
filmCount integer The number of films in the list.
published boolean Will be true if the owner has elected to publish the list for other members to see.
ranked boolean Will be true if the owner has elected to make this a ranked list.
descriptionLbml string The list description in LBML. May contain the following HTML tags: <br> <strong> <em> <b> <i> <a href=""> <blockquote>. The text is a preview extract, and may be truncated if it’s too long.
descriptionTruncated boolean Will be true if the list description was truncated because it’s very long.
owner MemberSummary The member who owns the list.
clonedFrom ListIdentifier The list this was cloned from, if applicable.
previewEntries
ListEntrySummary[]
 		The first 12 entries in the list. To fetch more than 12 entries, and to fetch the entry notes, use the /list/{id}/entries endpoint.
description string The list description formatted as HTML. The text is a preview extract, and may be truncated if it’s too long.

ListUpdateEntry

Properties

film 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 stay in the same place (if already in the list) or be appended to the end of the list (if not in the list). If set, any entries at or after this position will be incremented by one. Sending two or more ListUpdateEntrys with the same rank will return an error.
notes string The notes for the list entry in LBML. May contain the following HTML tags: <br> <strong> <em> <b> <i> <a href=""> <blockquote>. This field has a maximum size of 100,000 characters.
containsSpoilers boolean Set to true if the member has indicated that the notes field contains plot spoilers for the film.

ListUpdateMessage

Properties

type enum ∈ {Error, Success} The type of message.
code enum ∈ {ListNameIsBlank, UnknownFilmCode, InvalidRatingValue, DuplicateRank, EmptyPublicList, SharingServiceNotAuthorized, CannotSharePrivateList, ListDescriptionIsTooLong, ListEntryNotesTooLong} The error message code.
title string The error message text in human-readable form.

ListUpdateRequest

Properties

published boolean Set to true if the owner has elected to publish the list for other members to see.
name string The name of the list.
commentPolicy enum ∈ {Anyone, Friends, You} The policy determining who can post comments to the list. You in this context refers to the content owner. Use the commentThreadState property of the ListRelationship to determine the signed-in member’s ability to comment (or not).
ranked boolean Set to true if the owner has elected to make this a ranked list.
description string The list description in LBML. May contain the following HTML tags: <br> <strong> <em> <b> <i> <a href=""> <blockquote>. This field has a maximum size of 100,000 characters.
tags
string[]
 		The tags for the list.
filmsToRemove
string[]
 		Specify the LIDs of films to be removed from the list.
entries
ListUpdateEntry[]
 		The specified entries will be inserted/appended to the list if they are not already present, or updated if they are present.
share
enum[] ∈ {Facebook}
The third-party service or services to which this list should be shared. Valid options are found in the ListRelationship (see the /list/{id}/me endpoint).DEPRECATED No longer supported by Facebook.

ListUpdateResponse

Properties

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

ListsRequest

Properties

cursor Cursor The pagination cursor.
perPage integer The number of items to include per page (default is 20, maximum is 100).
sort enum ∈ {Date, WhenPublishedLatestFirst, WhenPublishedEarliestFirst, WhenCreatedLatestFirst, WhenCreatedEarliestFirst, ListName, ListPopularity, ListPopularityThisWeek, ListPopularityThisMonth, ListPopularityThisYear, ListPopularityWithFriends, ListPopularityWithFriendsThisWeek, ListPopularityWithFriendsThisMonth, ListPopularityWithFriendsThisYear} Defaults to Date, which returns lists that were most recently created/updated first. The ListPopularityWithFriends values are only available to signed-in members and consider popularity amongst the signed-in member’s friends.
film string Specify the LID of a film to return lists that include that film.
clonedFrom string Specify the LID of a list to return lists that were cloned from that list.
tag string DEPRECATED Use tagCode instead.
tagCode string Specify a tag code to limit the returned lists 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.
member 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 enum ∈ {Owner, Liked} Must be used in conjunction with member. Defaults to Owner, which returns lists owned by the specified member. Use Liked to return lists liked by the member.
includeFriends enum ∈ {None, 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
enum[] ∈ {Clean, Published, NotPublished}
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 unpublished 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
enum[] ∈ {NoDuplicateMembers}
Specify NoDuplicateMembers to limit the list to only the first list for each member. NoDuplicateMembers is only available when using these sort orders: Date, WhenPublishedLatestFirst, WhenCreatedLatestFirst. 
filter=NoDuplicateMembers

ListsResponse

Properties

next Cursor The cursor to the next page of results.
items
ListSummary[]
 		The list of lists.

LogEntriesRequest

Properties

cursor Cursor The pagination cursor.
perPage integer The number of items to include per page (default is 20, maximum is 100).
sort enum ∈ {WhenAdded, Date, 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 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).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 ReviewPopularityWithFriends and FilmPopularityWithFriends 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, EntryRatingHighToLow, EntryRatingLowToHigh or any ReviewPopularity sort order.DEPRECATED The RatingHighToLow and RatingLowToHigh options are deprecated in favor of EntryRatingHighToLow and EntryRatingLowToHigh.
film string Specify the LID of a film to return log entries for that film. Must not be included if the sort value is ReleaseDateLatestFirst, ReleaseDateEarliestFirst, FilmName, FilmDurationShortestFirst, FilmDurationLongestFirst, or any of the FilmPopularity options.
member string Specify the LID of a member to limit the returned log entries according to the value set in memberRelationship or to access the MemberRatingHighToLow and MemberRatingLowToHigh sort options.
memberRelationship 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 enum ∈ {Ignore, Watched, NotWatched, Liked, NotLiked, 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 enum ∈ {None, 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 integer If set, limits the returned log entries to those with date that falls during the specified year.
month 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 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 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 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 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 integer Specify the starting year of a decade (must end in 0) to limit films to those released during the decade. 
1990
filmYear integer Specify a year to limit films to those released during that year. 
1994
genre string The LID of the genre. If set, limits the returned log entries to those for films that match the specified genre.
tag string DEPRECATED Use tagCode instead.
tagCode string Specify a tag code to limit the returned log entries 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.
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.
where
enum[] ∈ {HasDiaryDate, HasReview, Clean, NoSpoilers, Released, NotReleased, FeatureLength, NotFeatureLength, InWatchlist, NotInWatchlist, Watched, NotWatched, Rated, NotRated}
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. 
where=Clean&where=NoSpoilers
filter
enum[] ∈ {NoDuplicateMembers}
Specify NoDuplicateMembers to return only the first log entry for each member. If film is not provided, only recent Log Entries will be returned (i.e. entries logged in the past 30 days). NoDuplicateMembers is only available when using these sort orders: WhenAdded, Date, ReviewPopularity, ReviewPopularityThisWeek, ReviewPopularityThisMonth, ReviewPopularityThisYear. You may not use NoDuplicateMembers with filmMemberRelationship, filmDecade, filmYear, genre, tagCode, service, or where except HasDiaryDate, HasReview, Clean, and/or NoSpoilers. 
filter=NoDuplicateMembers

LogEntriesResponse

Properties

next Cursor The cursor to the next page of results.
items
LogEntry[]
 		The list of log entries.

LogEntry

Properties

id string The LID of the log entry.
name string A descriptive title for the log entry.
owner MemberSummary The member who created the log entry.
film FilmSummary The film being logged. Includes a MemberFilmRelationship for the member who created the log entry.
diaryDetails DiaryDetails Details about the log entry, if present.
review Review Review details for the log entry, if present.
tags
string[]
 		DEPRECATED Use tags2 instead.
tags2
Tag[]
 		The tags for the log entry.
whenCreated string The timestamp of when the log entry was created, in ISO 8601 format with UTC timezone, i.e. YYYY-MM-DDThh:mm:ssZ 
"1997-08-29T07:14:00Z"
whenUpdated string The timestamp of when the log entry was last updated, in ISO 8601 format with UTC timezone, i.e. YYYY-MM-DDThh:mm:ssZ 
"1997-08-29T07:14:00Z"
rating number The member’s rating for the film. Allowable values are between 0.5 and 5.0, with increments of 0.5.
like boolean Will be true if the member likes the film (via the ‘heart’ icon).
commentable boolean Will be true if comments can be posted to the log entry by the member. This is determined according to the existence of review text and other factors such as the content owner’s comment policy.
commentPolicy enum ∈ {Anyone, Friends, You} The policy determining who can post comments to the log entry. You in this context refers to the content owner. Use the commentThreadState property of the ListRelationship to determine the signed-in member’s ability to comment (or not).
links
Link[]
 		A list of relevant URLs for this entity, on Letterboxd and external sites.

LogEntryCreationRequest

Properties

filmId Required string The film being logged.
diaryDetails LogEntryCreationRequestDiaryDetails Information about this log entry if adding to the member’s diary.
review LogEntryCreationRequestReview Information about the review if adding a review.
tags
string[]
 		The tags for the log entry.
rating number Allowable values are between 0.5 and 5.0, with increments of 0.5.
like boolean Set to true if the member likes the review (via the ‘heart’ icon). A member may not like their own review.
commentPolicy enum ∈ {Anyone, Friends, You} The policy determining who can post comments to the log entry. You in this context refers to the content owner. Use the commentThreadState property of the ListRelationship to determine the signed-in member’s ability to comment (or not).

LogEntryCreationRequestDiaryDetails

Properties

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

LogEntryCreationRequestReview

Properties

text Required string The review text in LBML. May contain the following HTML tags: <br> <strong> <em> <b> <i> <a href=""> <blockquote>. This field has a maximum size of 100,000 characters.
containsSpoilers boolean Set to true if the member has indicated that the review field contains plot spoilers for the film.
share
enum[] ∈ {Facebook}
The third-party service or services to which this review should be shared. Valid options are found in the MemberAccount.authorizedSharingServicesForReviews (see the /me endpoint).DEPRECATED No longer supported by Facebook.

LogEntryUpdateMessage

Properties

type enum ∈ {Error, Success} The type of message.
code enum ∈ {InvalidRatingValue, InvalidDiaryDate, ReviewWithNoText, ReviewIsTooLong, LogEntryWithNoReviewOrDiaryDetails} The error message code.
title string The error message text in human-readable form.

LogEntryUpdateRequest

Properties

diaryDetails LogEntryUpdateRequestDiaryDetails Information about this log entry if adding to the member’s diary. Set to null to remove this log entry from the diary.
review LogEntryUpdateRequestReview Information about the review. Set to null to remove the review from this log entry.
tags
string[]
 		The tags for the log entry.
rating number Accepts values between 0.5 and 5.0, with increments of 0.5, or null (to remove the rating).
like boolean Set to true if the member likes the review (via the ‘heart’ icon). A member may not like their own review.
commentPolicy enum ∈ {Anyone, Friends, You} The policy determining who can post comments to the log entry. You in this context refers to the content owner. Use the commentThreadState property of the ListRelationship to determine the signed-in member’s ability to comment (or not).

LogEntryUpdateRequestDiaryDetails

Properties

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

LogEntryUpdateRequestReview

Properties

text string The review text 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 review field contains plot spoilers for the film.
share
enum[] ∈ {Facebook}
The third-party service or services to which this review should be shared. Valid options are found in the ReviewRelationship.canShareOn (see the /log-entry/{id}/me endpoint).DEPRECATED No longer supported by Facebook.

LoginTokenResponse

Properties

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

Member

Properties

id string The LID of the member.
username string The member’s Letterboxd username. Usernames must be between 2 and 15 characters long and may only contain upper or lowercase letters, numbers or the underscore (_) character.
givenName string The given name of the member.
familyName string The family name of the member.
displayName string A convenience method that returns the member’s given name and family name concatenated with a space, if both are set, or just their given name or family name, if one is set, or their username, if neither is set. Will never be empty.
shortName string A convenience method that returns the member’s given name, if set, or their username. Will never be empty.
pronoun Pronoun The member’s preferred pronoun. Use the /members/pronouns endpoint to request all available pronouns.
commentPolicy enum ∈ {Anyone, Friends, You} The member’s default policy determing who can post comments to their content. Supported options are Anyone, Friends and You. You in this context refers to the content owner. Use the commentThreadState property of the ListRelationship to determine the signed-in member’s ability to comment (or not).
twitterUsername string The member’s Twitter username, if they have authenticated their account.
bioLbml string The member’s bio in LBML. May contain the following HTML tags: <br> <strong> <em> <b> <i> <a href=""> <blockquote>.
location string The member’s location.
website string The member’s website URL. URLs are not validated, so sanitizing may be required.
avatar Image The member’s avatar image at multiple sizes. Avatar images to not have an enforced aspect ratio, so should be center-cropped to a square if they are not 1:1.
backdrop Image The member’s backdrop image at multiple sizes, sourced from the first film in the member’s list of favorite films, if available. Only returned for Patron members.
backdropFocalPoint number The vertical focal point of the member’s backdrop image, if available. Expressed as a proportion of the image’s height, using values between 0.0 and 1.0. Use when cropping the image into a shorter space, such as in the page for a film on the Letterboxd site.
memberStatus enum ∈ {Crew, Patron, Pro, Member} The member’s account type.
favoriteFilms
FilmSummary[]
 		A summary of the member’s favorite films, up to a maximum of four.
pinnedReviews
LogEntry[]
 		The reviews the member has pinned on their profile page, up to a maximum of two. Only returned for paying members.
links
Link[]
 		A link to the member’s profile page on the Letterboxd website.
privateWatchlist boolean Defaults to false for new accounts. Indicates whether the member has elected to hide their watchlist from other members.
bio string The member’s bio formatted as HTML.

MemberAccount

Properties

emailAddress string The member’s email address.
emailAddressValidated boolean Will be true if the member has validated their emailAddress via an emailed link.
privateAccount boolean Defaults to false for new accounts. Indicates whether the member has elected for their content to appear in the API (other than in the /me endpoint).
includeInPeopleSection boolean Defaults to true for new accounts. Indicates whether the member has elected to appear in the People section of the Letterboxd website.
privateWatchlist boolean Defaults to false for new accounts. Indicates whether the member has elected to hide their watchlist from other members.DEPRECATED Found in member instead.
emailWhenFollowed boolean Defaults to true for new accounts. Indicates whether the member has elected to receive an email notification when someone new follows them.
emailComments boolean Defaults to true for new accounts. Indicates whether the member has elected to receive email notifications when new comments are posted in threads they are subscribed to.
emailNews boolean Defaults to true for new accounts. Indicates whether the member has elected to receive regular email news (including ‘Call Sheet’) from Letterboxd.
emailRushes boolean Defaults to true for new accounts. Indicates whether the member has elected to receive a weekly email digest of new and popular content (called ‘Rushes’).
devicesRegisteredForPushNotifications
string[]
 		The list of device IDs that may receive push notifications for this account.
pushNotificationsForGeneralAnnouncements boolean Defaults to true for new accounts. Indicates whether the member has elected to receive push notifications for service and account alerts.
pushNotificationsForComments boolean Defaults to true for new accounts. Indicates whether the member has elected to receive push notifications when new comments are posted to content they are subscribed to.
pushNotificationsForListLikes boolean Defaults to true for new accounts. Indicates whether the member has elected to receive push notifications when another member likes one of their lists.
pushNotificationsForReviewLikes boolean Defaults to true for new accounts. Indicates whether the member has elected to receive push notifications when another member likes one of their reviews.
pushNotificationsForNewFollowers boolean Defaults to true for new accounts. Indicates whether the member has elected to receive push notifications when another member follows them.
canComment boolean Defaults to false for new accounts. Indicates whether the member has commenting privileges. Commenting is disabled on new accounts until the member’s emailAddress is validated. At present canComment is synonymous with emailAddressValidated (unless the member is suspended) but this may change in future.
suspended boolean Indicates whether the member is suspended from commenting due to a breach of the Community Policy.
canCloneLists boolean Indicates whether the member is able to clone other members’ lists. Determined by Letterboxd based upon memberStatus.
canFilterActivity boolean Indicates whether the member is able to filter activity by type. Determined by Letterboxd based upon memberStatus.
authorizedSharingServicesForLists
enum[] ∈ {Facebook}
The services the member has authorized Letterboxd to share lists to. More services may be added in the future.DEPRECATED No longer supported by Facebook.
authorizedSharingServicesForReviews
enum[] ∈ {Facebook}
The services the member has authorized Letterboxd to share reviews to. More services may be added in the future.DEPRECATED No longer supported by Facebook.
membershipDaysRemaining integer The number of days the member has left in their subscription. Only returned for paying members.
membershipWillAutoRenewViaIAP boolean Indicates whether the member’s subscription is expected to auto-renew via Apple’s IAP subscription. Only returned for members who have subscribed through IAP.
member Member Standard member details.
campaigns
string[]
 		The list of campaigns this account is involved in.

MemberFilmRelationship

Properties

member MemberSummary The member.
relationship FilmRelationship The relationship details.

MemberFilmRelationshipsRequest

Properties

cursor Cursor The pagination cursor.
perPage integer The number of items to include per page (default is 20, maximum is 100).
sort enum ∈ {Date, Name, MemberPopularity, MemberPopularityThisWeek, MemberPopularityThisMonth, MemberPopularityThisYear, MemberPopularityWithFriends, MemberPopularityWithFriendsThisWeek, MemberPopularityWithFriendsThisMonth, MemberPopularityWithFriendsThisYear} 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 PopularWithFriends values are only available to authenticated members and consider popularity amongst the member’s friends.
member string Specify the LID of a member to return members who follow or are followed by that member.
memberRelationship enum ∈ {IsFollowing, 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 enum ∈ {Ignore, Watched, NotWatched, Liked, NotLiked, 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.

MemberFilmRelationshipsResponse

Properties

next Cursor The cursor to the next page of results.
items
MemberFilmRelationship[]
 		The list of film relationships for members.

MemberIdentifier

Properties

id string The LID of the member.

MemberRelationship

Properties

following boolean Will be true if the authenticated member follows the member identified by ID.
followedBy boolean Will be true if the member identified by ID follows the authenticated member.
blocking boolean Will be true if the authenticated member has blocked the member identified by ID.
blockedBy boolean Will be true if the member identified by ID has blocked the authenticated member.

MemberRelationshipUpdateMessage

Properties

type enum ∈ {Error, Success} The type of message.
code enum ∈ {BlockYourself, FollowYourself, FollowBlockedMember, FollowMemberYouBlocked} The error message code.
title string The error message text in human-readable form.

MemberRelationshipUpdateRequest

Properties

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

MemberRelationshipUpdateResponse

Properties

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

MemberSearchItem < AbstractSearchItem

Inherited Properties

score Inherited number A relevancy value that can be used to order results.

Properties

score number A relevancy value that can be used to order results.
member MemberSummary The member returned by the search.

MemberSettingsUpdateMessage

Properties

type enum ∈ {Error, Success} The type of message.
code enum ∈ {IncorrectCurrentPassword, BlankPassword, InvalidEmailAddress, InvalidFavoriteFilm, BioTooLong, InvalidPronounOption} The error message code.
title string The error message text in human-readable form.

MemberSettingsUpdateRequest

Properties

emailAddress string The member’s email address.
currentPassword string The member’s current password. Required when updating the password.
password string The member’s new password.
givenName string The given name of the member.
familyName string The family name of the member.
pronoun string The LID of the member’s preferred pronoun. Use the /members/pronouns endpoint to request all available pronouns.
commentPolicy string The member’s default policy determing who can post comments to their content. Supported options are Anyone, Friends and You. You in this context refers to the content owner. Use the commentThreadState property of the ListRelationship to determine the signed-in member’s ability to comment (or not).
location string The member’s location.
website string The member’s website URL. URLs are not validated, so sanitizing may be required.
bio string The member’s bio in LBML. May contain the following HTML tags: <br> <strong> <em> <b> <i> <a href=""> <blockquote>. This field has a maximum size of 100,000 characters.
favoriteFilms
string[]
 		The LIDs of the member’s favorite films, in order, up to a maximum of four.
privateAccount boolean Set to true to prevent the member’s content from appearing in API requests other than the /me endpoint.
includeInPeopleSection boolean Set to false to remove the account from the People section of the Letterboxd website.
emailWhenFollowed boolean Set to true if the member wishes to receive an email notification when someone new follows them.
emailComments boolean Set to true if the member wishes to receive email notifications when new comments are posted in threads they are subscribed to.
emailNews boolean Set to true if the member wishes to receive regular email news (including ‘Call Sheet’) from Letterboxd.
emailRushes boolean Set to true if the member wishes to receive a weekly email digest of new and popular content (called ‘Rushes’).
pushNotificationsForGeneralAnnouncements boolean Set to true if the member wishes to receive push notifications for service and account alerts.
pushNotificationsForComments boolean Set to true if the member wishes to receive push notifications when new comments are posted to content they are subscribed to.
pushNotificationsForReviewLikes boolean Set to true if the member wishes to receive push notifications when another member likes one of their reviews.
pushNotificationsForListLikes boolean Set to true if the member wishes to receive push notifications when another member likes one of their lists.
pushNotificationsForNewFollowers boolean Set to true if the member wishes to receive push notifications when another member follows them.

MemberSettingsUpdateResponse

Properties

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

MemberStatistics

Properties

member MemberIdentifier The member for which statistics were requested.
counts MemberStatisticsCounts The number of watches, ratings, likes, etc. for the member.
ratingsHistogram
RatingsHistogramBar[]
 		A summary of the number of ratings the member has made for each increment between 0.5 and 5.0. Returns only the integer increments between 1.0 and 5.0 if the member never (or rarely) awards half-star ratings.
yearsInReview
integer[]
 		A list of years the member has year-in-review pages for. Only supported for paying members.

MemberStatisticsCounts

Properties

filmLikes integer The number of films the member has liked.
listLikes integer The number of lists the member has liked.
reviewLikes integer The number of reviews the member has liked.
watches integer The number of films the member has watched. This is a distinct total — films with multiple log entries are only counted once.
ratings integer The number of films the member has rated.
reviews integer The number of films the member has reviewed.
diaryEntries integer The number of entries the member has in their diary.
diaryEntriesThisYear integer The number of entries the member has in their diary for the current year. The current year rolls over at midnight on 31 December in New Zealand Daylight Time (GMT + 13).
filmsInDiaryThisYear integer The number of unique films the member has in their diary for the current year. The current year rolls over at midnight on 31 December in New Zealand Daylight Time (GMT + 13).
watchlist integer The number of films the member has in their watchlist.
lists integer The number of lists for the member. Includes unpublished lists if the request is made for the authenticated member.
unpublishedLists integer The number of unpublished lists for the member. Only included if the request is made for the authenticated member.
followers integer The number of members who follow the member.
following integer The number of members the member is following.
listTags integer The number of tags the member has used for lists.
filmTags integer The number of tags the member has used for diary entries and reviews.

MemberSummary

Properties

id string The LID of the member.
username string The member’s Letterboxd username. Usernames must be between 2 and 15 characters long and may only contain upper or lowercase letters, numbers or the underscore (_) character.
givenName string The given name of the member.
familyName string The family name of the member.
displayName string A convenience method that returns the member’s given name and family name concatenated with a space, if both are set, or just their given name or family name, if one is set, or their username, if neither is set. Will never be empty.
shortName string A convenience method that returns the member’s given name, if set, or their username. Will never be empty.
pronoun Pronoun The member’s preferred pronoun. Use the /members/pronouns endpoint to request all available pronouns.
avatar Image The member’s avatar image at multiple sizes. Avatar images to not have an enforced aspect ratio, so should be center-cropped to a square if they are not 1:1.
commentPolicy enum ∈ {Anyone, Friends, You} The member’s default policy determing who can post comments to their content. Supported options are Anyone, Friends and You. You in this context refers to the content owner. Use the commentThreadState property of the ListRelationship to determine the signed-in member’s ability to comment (or not).
memberStatus enum ∈ {Crew, Patron, Pro, Member} The member’s account type.

MemberTag

Properties

tag string DEPRECATED Use displayTag instead.
code string The tag code.
displayTag string The tag text as entered by the tagger.
counts MemberTagCounts Counts of the member’s uses of this tag.

MemberTagCounts

Properties

films integer The number of films the member has used this tag on.
logEntries integer The number of log entries the member has used this tag on.
diaryEntries integer The number of diary entries the member has used this tag on.
reviews integer The number of reviews the member has used this tag on.
lists integer The number of lists the member has used this tag on.

MemberTagsRequest

Properties

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

MemberTagsResponse

Properties

items
MemberTag[]
 		The list of tag items, ordered by frequency of use.

MembersRequest

Properties

cursor Cursor The pagination cursor.
perPage integer The number of items to include per page (default is 20, maximum is 100).
sort enum ∈ {Date, Name, MemberPopularity, MemberPopularityThisWeek, MemberPopularityThisMonth, MemberPopularityThisYear, MemberPopularityWithFriends, MemberPopularityWithFriendsThisWeek, MemberPopularityWithFriendsThisMonth, MemberPopularityWithFriendsThisYear} 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 PopularWithFriends values are only available to authenticated members and consider popularity amongst the member’s friends.
member string Specify the LID of a member to return members who follow or are followed by that member.
memberRelationship enum ∈ {IsFollowing, 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 string Specify the LID of a film to return members who have interacted with that film.
filmRelationship enum ∈ {Ignore, Watched, NotWatched, Liked, NotLiked, 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 the InWatchlist relationship.
list string Specify the LID of a list to return members who like that list.
review string Specify the LID of a review to return members who like that review.

MembersResponse

Properties

next Cursor The cursor to the next page of results.
items
MemberSummary[]
 		The list of members.

NewsItem

Properties

title string The title of the news item.
image Image The image.
url string The URL of the news item.
shortDescription string A short description of the news item in LBML. May contain the following HTML tags: <br> <strong> <em> <b> <i> <a href=""> <blockquote>.
longDescription string A long description of the news item in LBML. May contain the following HTML tags: <br> <strong> <em> <b> <i> <a href=""> <blockquote>.

NewsRequest

Properties

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

NewsResponse

Properties

next Cursor The cursor to the next page of results.
items
NewsItem[]
 		The list of news items.

OAuthError

Properties

error string The error code, usually invalid_grant.

Pronoun

Properties

id string The LID for this pronoun.
label string A label to describe this pronoun.
subjectPronoun string The pronoun to use when the member is the subject. 
She went to the movies.
objectPronoun string The pronoun to use when the member is the object. 
I went with her to the cinema.
possessiveAdjective string The adjective to use when describing a specified thing or things belonging to or associated with a member previously mentioned. 
He bought his tickets.
possessivePronoun string The pronoun to use when referring to a specified thing or things belonging to or associated with a member previously mentioned. 
That popcorn was hers.
reflexive string The pronoun to use to refer back to the member. 
He saw himself as a great director.

PronounsResponse

Properties

items
Pronoun[]
 		The list of pronouns.

RatingsHistogramBar

Properties

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

RegisterPushNotificationsRequest

Properties

deviceId Required string The device ID.
deviceName string The device name.
token Required string The Firebase token.

RegisterRequest

Properties

username string The username for the new account. Use the /auth/username-check endpoint to check availability.
password string The password for the new account.
emailAddress string The email address for the new account.
acceptTermsOfUse boolean Set to true if the person creating the account has agreed to being at least 16 years of age, and to accepting Letterboxd’s Terms of Use.

RegistrationActivity < 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

type RegistrationActivity
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"

ReportCommentRequest

Properties

reason Required enum ∈ {Abuse, Spoilers, Spam, Plagiarism, Other} The reason why the comment was reported.
message string An optional, explanatory message to accompany the report. Required if the reason is Plagiarism or Other.

ReportFilmRequest

Properties

reason Required enum ∈ {Duplicate, NotAFilm, Other} The reason why the film was reported.
message string An optional, explanatory message to accompany the report. Required if the reason is Duplicate or Other.

ReportListRequest

Properties

reason Required enum ∈ {Abuse, Spoilers, Spam, Plagiarism, Other} The reason why the list was reported.
message string An optional, explanatory message to accompany the report. Required if the reason is Plagiarism or Other.

ReportMemberRequest

Properties

reason Required enum ∈ {SpamAccount, Other} The reason why the member was reported.
message string An optional, explanatory message to accompany the report. Required if the reason is Other.

ReportReviewRequest

Properties

reason Required enum ∈ {Abuse, Spoilers, Spam, Plagiarism, Other} The reason why the review was reported.
message string An optional, explanatory message to accompany the report. Required if the reason is Plagiarism or Other.

Review

Properties

lbml string The review text in LBML. May contain the following HTML tags: <br> <strong> <em> <b> <i> <a href=""> <blockquote>.
containsSpoilers boolean Will be true if the member has indicated that the review field contains plot spoilers for the film.
moderated boolean Will be true if the review has been removed by a moderator.
canShareOn
enum[] ∈ {Facebook}
The third-party service or services to which this review can be shared. Only included if the authenticated member is the review’s owner.DEPRECATED No longer supported by Facebook.
sharedOn
enum[] ∈ {Facebook}
The third-party service or services to which this review has been shared. Only included if the authenticated member is the review’s owner.DEPRECATED No longer supported by Facebook.
whenReviewed string The timestamp when this log entry’s review was first published, in ISO 8601 format with UTC timezone, i.e. YYYY-MM-DDThh:mm:ssZ 
"1997-08-29T07:14:00Z"
text string The review text formatted as HTML.

ReviewActivity < 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

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"
review LogEntry The log entry associated with this activity

ReviewComment

Properties

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 review 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.
review ReviewIdentifier The review on which the comment was posted.
comment string The message portion of the comment formatted as HTML.

ReviewCommentActivity < 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

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"
review LogEntry The review associated with the activity.
comment ReviewComment The comment associated with the activity.

ReviewCommentsResponse

Properties

next Cursor The cursor to the next page of results.
items
ReviewComment[]
 		The list of comments.

ReviewIdentifier

Properties

id string The LID of the log entry.

ReviewLikeActivity < 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

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"
review LogEntry The review associated with the activity.

ReviewRelationship

Properties

liked boolean Will be true if the member likes the review (via the ‘heart’ icon). A member may not like their own review.
subscribed boolean Will be true if the member is subscribed to comment notifications for the review
subscriptionState enum ∈ {Subscribed, NotSubscribed, Unsubscribed} Defaults to Subscribed for the review’s author, and NotSubscribed for other members. The subscription value may change when a member (other than the owner) posts a comment, as follows: the member will become automatically Subscribed unless they have previously Unsubscribed from the comment thread via the web interface or API, or unless they have disabled comment notifications in their 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 ∈ {Banned, Blocked, BlockedThem, CanComment, Closed, FriendsOnly, Moderated, NotCommentable, NotValidated} The authenticated member’s state with respect to adding comments for this review.Banned means the Letterboxd community managers have restricted the member’s ability to post comments.Blocked means the owner has blocked the member from posting comments.BlockedThem means the member has blocked the owner and is therefore unable to post comments.CanComment means the authenticated member is authorized to post a comment (also known as a “reply”). All other values mean the authenticated member is not authorized to post a comment.Closed means the owner has closed the comment thread to all other members.FriendsOnly means the owner is only accepting comments from members they follow.Moderated means the Letterboxd community managers have removed the content (applies to reviews only).NotCommentable means that comments may not be posted to this thread.NotValidated means the owner has not validated their email address.

ReviewRelationshipUpdateMessage

Properties

type enum ∈ {Error, Success} The type of message.
code enum ∈ {LikeBlockedContent, LikeOwnReview, LikeRemovedReview, LikeLogEntryWithoutReview, SubscribeWhenOptedOut, SubscribeToContentYouBlocked, SubscribeToBlockedContent} The error message code.
title string The error message text in human-readable form.

ReviewRelationshipUpdateRequest

Properties

liked boolean Set to true if the member likes the review (via the ‘heart’ icon). A member may not like their own review.
subscribed boolean Set to true to subscribe the member to comment notifications for the review, or false to unsubscribe them. A value of true will be ignored if the member has disabled comment notifications in their profile settings.

ReviewRelationshipUpdateResponse

Properties

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

ReviewSearchItem < AbstractSearchItem

Inherited Properties

score Inherited number A relevancy value that can be used to order results.

Properties

score number A relevancy value that can be used to order results.
review LogEntry Details of the review.

ReviewStatistics

Properties

logEntry ReviewIdentifier The log entry for which statistics were requested.
counts ReviewStatisticsCounts The number of comments and likes for the review.

ReviewStatisticsCounts

Properties

comments integer The number of comments for the review.
likes integer The number of members who like the review.

ReviewUpdateResponse

Properties

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

SearchRequest

Properties

cursor Cursor The pagination cursor.
perPage integer The number of items to include per page (default is 20, maximum is 100).
input Required string The word, partial word or phrase to search for.
searchMethod enum ∈ {FullText, Autocomplete} 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
enum[] ∈ {ContributorSearchItem, FilmSearchItem, ListSearchItem, MemberSearchItem, ReviewSearchItem, TagSearchItem}
The types of results to search for. Default to all SearchResultTypes.
contributionType enum ∈ {Director, CoDirector, Actor, Producer, Writer, Editor, Cinematography, ProductionDesign, ArtDirection, SetDecoration, VisualEffects, Composer, Sound, Costumes, MakeUp, Studio} The type of contributor to search for. Implies include=ContributorSearchItem.

SearchResponse

Properties

next Cursor The cursor to the next page of results.
items
AbstractSearchItem[]
 		The list of search results.

Service

Properties

id string The LID of the service.
name string The name of the service.
icon string The URL of the thumbnail image for the service.

Tag

Properties

tag string DEPRECATED Use displayTag instead.
code string The tag code.
displayTag string The tag text as entered by the tagger.

TagSearchItem < AbstractSearchItem

Inherited Properties

score Inherited number A relevancy value that can be used to order results.

Properties

score number A relevancy value that can be used to order results.
tag Tag The tag.

TagsResponse

Properties

items
string[]
 		The list of tags, ordered by frequency of use.

UsernameCheckResponse

Properties

result enum ∈ {Available, NotAvailable, TooShort, TooLong, Invalid} Will be Available if the username is available to register, or NotAvailable if used by another member (or attached to a deactivated account, or otherwise reserved). May return an appropriate error value if the username doesn’t meet Letterboxd’s requirements: Usernames must be between 2 and 15 characters long and may only contain upper or lowercase letters, numbers or the underscore (_) character.

WatchlistActivity < 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

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"
film FilmSummary The film associated with the activity. Includes a MemberFilmRelationship for the member who added the activity.

WatchlistRequest

Properties

cursor Cursor The pagination cursor.
perPage integer The number of items to include per page (default is 20, maximum is 100).
sort enum ∈ {Added, 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 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 </