Overview
The Letterboxd API provides access to data on the Letterboxd.com website.
The API consists of endpoints that must be called using HTTPS.
Each endpoint URL takes the form of https://api.letterboxd.com/api/v0/ENDPOINT_PATH
and should be called using the method specified in the relevant documentation (GET, POST, PATCH or DELETE).
For GET requests, parameters other than the path parameter (if one is specified for the endpoint) should be included as query parameters in the URL.
For POST, PATCH and DELETE requests, all required parameters should be included in JSON format within the body of the request.
For PATCH requests, you need only include the parameters that are to be changed as a result of the request. If PATCH requests aren’t supported by your client, you can specify a header of X-HTTP-Method-Override: PATCH
to simulate these.
Entities are identified in the API by Letterboxd ID (or LID), an alpha-numeric string value that is returned by the API where appropriate.
For films, lists and reviews, the LID can also be found through the Letterboxd website as the path portion of the entity’s shareable boxd.it
URL.
Member LIDs are included in the response headers of an HTTP request for the member’s profile page (as x-letterboxd-identifier
) and can also be found via the shareable boxd.it
URL of the member’s profile in our iOS app.
In all cases the response from an endpoint will be a JSON object, with HTTP status codes indicating successful results and error states.
Authentication
The Letterboxd API uses standard OAuth 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 /auth/forgotten-password-request
Request a link via email to reset the password for a member’s account.
Response
204 |
Success (the email was dispatched if it matched an existing account) |
|
400 |
Bad request |
|
429 |
Too many forgotten password requests have been received for this email address. 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 |
|
400 |
The credentials were not correct for the member, or the account was not found. |
|
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. |
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 |
|
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
Parameters
id Required |
string
|
path |
The LID of the contributor. |
Response
200 |
Success |
|
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.
Parameters
id Required |
string
|
path |
The LID of the film collection. |
Response
200 |
Success |
|
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 |
|
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 |
|
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 |
|
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).
Parameters
id Required |
string
|
path |
The LID of the film. |
Response
200 |
Success |
|
401 |
There is no authenticated member |
|
404 |
No film matches the specified ID |
|
GET /film/{id}/members
Get details of members’ relationships with a film by ID.
Parameters
id Required |
string
|
path |
The LID of the film. |
Response
200 |
Success |
|
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).
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 |
|
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.
GET /films/film-services
Get a list of services supported by the /films endpoint.
Services are returned in alphabetical order. Some services are only available to paying members, so results will vary based on the authenticated member’s status.
GET /films/genres
Get a list of genres supported by the /films endpoint.
Genres are returned in alphabetical order.
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 |
|
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).
Parameters
id Required |
string
|
path |
The LID of the list. |
Response
200 |
Success |
|
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}/entries
Get entries for a list by ID.
Parameters
id Required |
string
|
path |
The LID of the list. |
Response
200 |
Success |
|
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 |
|
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).
Parameters
id Required |
string
|
path |
The LID of the list. |
Response
200 |
Success |
|
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).
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 |
|
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.
Response
200 |
Success |
|
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).
Response
200 |
Success |
|
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.
Response
200 |
Success |
|
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).
Response
201 |
Success |
|
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 |
|
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).
Parameters
id Required |
string
|
path |
The LID of the log entry. |
Response
200 |
Success |
|
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}/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 |
|
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).
Parameters
id Required |
string
|
path |
The LID of the log entry. |
Response
200 |
Success |
|
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).
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 |
|
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 |
|
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).
Response
200 |
Success |
|
400 |
Bad request |
|
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 |
|
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.
Parameters
id Required |
string
|
path |
The LID of the member. |
Response
200 |
Success |
|
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.
Parameters
id Required |
string
|
path |
The LID of the member. |
Response
200 |
Success |
|
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 |
|
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).
Parameters
id Required |
string
|
path |
The LID of the other member. |
Response
200 |
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 |
|
POST /member/{id}/report
Report a 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 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}/statistics
Get statistical data about a member by ID.
Parameters
id Required |
string
|
path |
The LID of the member. |
Response
200 |
Success |
|
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.
Parameters
id Required |
string
|
path |
The LID of the member. |
Response
200 |
Success |
|
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.
GET /members/pronouns
Get a list of pronouns supported by the PATCH
/me endpoint.
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.
Response
201 |
Success |
|
400 |
The username was already taken or is invalid. |
|
GET /news
Get recent news from the Letterboxd editors.