An unofficial Letterboxd API client.
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 RevoltUser 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. |