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

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 can be deleted up to 15 minutes after they are first received by the server.

Parameters

id Required string path The LID of the comment.

Response

204 Success
400 Bad request
401 There is no authenticated member, or the authenticated member is not the owner of 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 are editable for 15 minutes after they are first received by the server.

Request

CommentUpdateRequest

Parameters

id Required string path The LID of the comment.

Response

200 Completed, possibly with messages.
CommentUpdateResponse
401 There is no authenticated member, or the authenticated member is not the owner of 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.

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 about a film by ID.

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 is not the owner of 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 is not the owner of 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 is not the owner of 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 is not the owner of 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).

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

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

Request

LogEntryCreationRequest

Response

201 Success
LogEntry
204 You already created this log entry. No action was taken.
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 is not the owner of 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 requested. The email is probably in the member’s spam 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.
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.
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, ArtDirection, 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 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, ArtDirection, 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, ArtDirection, 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, ArtDirection, 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, ArtDirection, 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, ArtDirection, 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 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 list of relevant URLs for this entity, on Letterboxd and external sites.

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

Properties

id string The LID of the comment.
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.
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.
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