An unofficial Letterboxd API client. 📽️

---

• Installation
• Usage
  • User Authentication
• Available APIs
  • Auth
  • Comments
  • Contributors
  • Film Collections
  • Films
  • Lists
  • Log Entries
  • Me
  • Members
  • News
  • Search
  • Stories
• FAQ

Installation

npm install letterboxd-client

Usage

import Client from 'letterboxd-client';
// const { default: Client } = require('letterboxd-client')

const apiKey = 'your letterboxd api key';
const apiSecret = 'your letterboxd api secret';

const client = new Client(apiKey, apiSecret);
const { status, data } = await client.film.get('ljDs');

console.log(data.name); // RRR
console.log(data.tagline); // Rise Roar Revolt

User Authentication

To authenticate a user you will need their Letterboxd credentials (username + password), which you will supply to client.auth.requestAuthToken like so:

const { status, data } = await client.auth.requestAuthToken(username, password);

If successful you will receive back an AccessToken response that will contain the users acessToken that you can then pass back into the main Client instance in order to authenticate all API requests as that user.

Available APIs

Note

For all documentation on parameters or responses see the TypeScript types that we export to the package or consult https://api-docs.letterboxd.com/ for the endpoint you're using.

_{* Requires an authenticated Letterboxd user access token.}

Auth

The following methods are available on the client.auth.* namespace:

Method	Description
#forgottenPasswordRequest()	Request a link via email to reset the password for a member's account.
#getLoginToken()*	Generate a single-use token for the current member, which can be used to sign the member into the Letterboxd website by passing it as the value of the urt query parameter.
#requestAuthToken()	Use a member's credentials to sign in and receive an authentication token.
#revokeAuth()*	Revoke a users' access token.
#usernameCheck()	Check if a username is available to register.

Comments

The following methods are available on the client.comment.* namespace:

Method	Description
#report()*	Report a comment by ID.
#update()*	Update the message portion of a comment.

Contributors

The following methods are available on the client.contributor.* namespace:

Method	Description
#getContributor()	Get details about a film contributor by ID.
#getContributions()	A cursored window over the list of contributions to films for a contributor.

Film Collections

The following methods are available on the client.filmCollection.* namespace:

Method	Description
#get()	Get details about a film collection by ID.

Films

The following methods are available on the client.film.* namespace:

Method	Description
#all()	A cursored window over the list of films.
#countries()	Get a list of countries supported by the /films endpoint.
#genres()	Get a list of genres supported by the /films endpoint.
#get()	Get details about a film by ID.
#getMemberFriends()	Get details of the authenticated member's friends' relationship with a film by ID.
#getMemberRelationship()*	Get details of the authenticated member's relationship with a film by ID.
#getMembers()	Get details of members' relationships with a film by ID.
#languages()	Get a list of languages supported by the /films endpoint.
#report()*	Report a film by ID.
#services()	Get a list of services supported by the /films endpoint.
#statistics()	Get statistical data about a film by ID.

Lists

The following methods are available on the client.list.* namespace:

Method	Description
#all()	A cursored window over a list of lists.
#create()*	Create a list.
#createComment()*	Create a comment on a list.
#delete()*	Delete a list by ID.
#get()	Get details of a list by ID.
#getComments()	A cursored window over the comments for a list.
#getEntries()	Get entries for a list by ID.
#getRelationship()*	Get details of the authenticated member's relationship with a list by ID.
#report()*	Report a list by ID.
#statistics()	Get statistical data about a list by ID.
#topics()	Get a list of featured topics/lists (e.g. for display in the Browse tab of our apps).
#update()*	Update a list by ID.
#updateLists()*	Add one or more films to one or more lists.
#updateRelationship()*	Update the authenticated member's relationship with a list by ID.

Log Entries

The following methods are available on the client.logEntry.* namespace:

Method	Description
#all()	A cursored window over the log entries for a film or member.
#create()*	Create a log entry.
#createComment()*	Create a comment on a review.
#delete()*	Delete a log entry by ID.
#get()	Get details about a log entry by ID.
#getRelationship()*	Get details of the authenticated member's relationship with a log entry's review by ID.
#getComments()	A cursored window over the comments for a log entry's review.
#report()*	Report a log entry's review by ID.
#statistics()	Get statistical data about a log-entry's review by ID.
#update()*	Update a log entry by ID.
#updateRelationship()*	Update the authenticated member's relationship with a log entry's review by ID.

Me

The following methods are available on the client.me.* namespace:

Method	Description
#deactivate()*	Deactivate account.
#deregisterPushNotifications()*	Deregister a device so it no longer receives push notifications.
#get()*	Get details about the authenticated member.
#registerPushNotifications()*	Register a device so it can receive push notifications.
#update()*	Update the profile settings for the authenticated member.
#validationRequest()*	Request a validation link via email.

Members

The following methods are available on the client.member.* namespace:

Method	Description
#all()	A cursored window over the list of members.
#get()	Get details about a member by ID.
#getMemberActivity()	A cursored window over the activity for a member.
#getMemberListTags()	Get the list of a member's tags, or those that match an optional search prefix.
#getMemberLogEntryTags()	Get the list of a member's tags, or those that match an optional search prefix.
#getMemberRelationship()*	Get details of the authenticated member's relationship with another member by ID.
#pronouns()	Get a list of pronouns supported by the PATCH /me endpoint
#register()	Create a new account.
#report()*	Report a member by ID.
#statistics()	Get statistical data about a member by ID.
#updateMemberRelationship()*	Update the authenticated member’s relationship with another member by ID.
#watchlist()	Get details of a member's public watchlist by ID.

News

client.news will return you back recent news from the Letterboxd editors at https://letterboxd.com/journal/.

Search

client.search is the main entry point for searching Letterboxd. See the parameter types or <a href="https://api-docs.letterboxd.com/#path--search>https://api-docs.letterboxd.com/#path--search for documentation.

Stories

The following methods are available on the client.story.* namespace:

Method	Description
#all()	A cursored window over a list of stories.
#get()	Get details of a story by ID.

FAQ

How can I get access to the Letterboxd API?

https://letterboxd.com/api-beta/