Letterboxd API endpoint
Searches Letterboxd for films, people, lists and tags by `q`, required. `type` can be set to `film` to return films only; `limit` defaults to 10 with a max of 50. Fields vary by result type: films carry `slug` and `year`, people carry `slug` and `role`, lists carry `owner`, and tags carry only a title and URL.
/letterboxd/searchQuery parameters:
q (required) — search query.type (optional) — result type filter. Allowed values: film. Omit for mixed results across films, people, lists, and tags.limit (optional, default 10, max 50).Response includes results[]. Field availability on each result varies by type: film hits carry slug and year; person hits carry slug and role (actor or director); list hits carry owner; tag hits are title+uri only.
| Field | Filled in, of 20 checked | Values in the sample |
|---|---|---|
| type | 20 | |
| title | 20 | |
| slug | 20 | |
| year | 19 | 1,925 to 2,024, median 2,006 |
| uri | 20 | letterboxd.com |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| q | string | Yes | Search query | Parasite | |
| type | string | No | Optional result type filter Allowed values: film. | ||
| limit | integer | No | Max results, default 10, max 50 | ||
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/letterboxd/search?q=Parasite&type=film&limit=10" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"query": "bong joon ho",
"results": [
{
"type": "person",
"title": "Bong Joon Ho",
"slug": "bong-joon-ho",
"role": "director",
"uri": "https://letterboxd.com/director/bong-joon-ho/"
},
{
"type": "list",
"title": "Bong Joon-ho",
"owner": "SilentDawn",
"uri": "https://letterboxd.com/silentdawn/list/bong-joon-ho/"
},
{
"type": "film",
"title": "Being John Malkovich",
"slug": "being-john-malkovich",
"year": 1999,
"uri": "https://letterboxd.com/film/being-john-malkovich/"
},
{
"type": "tag",
"title": "bong-joon-ho",
"uri": "https://letterboxd.com/tag/bong-joon-ho/"
}
],
"source_url": "https://letterboxd.com/s/search/bong%20joon%20ho/"
}
}Request schema
No body schema
Response schema
#/definitions/letterboxd.searchResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | letterboxd.SearchResponse | No | ||||
| data.query | string | No | Search text that was run. | |||
| data.results | array | No | Search hits, one item per film, person, list or tag. | |||
| data.results[].owner | string | No | Username of the member who made the list. Present for list hits. | |||
| data.results[].role | string | No | director | Role of the person, `actor` or `director`. Present for person hits. | ||
| data.results[].slug | string | No | Letterboxd slug of the film or person. Present for film and person hits. | |||
| data.results[].title | string | No | Title of the film or list, name of the person, or the tag. | |||
| data.results[].type | string | No | film | Kind of hit: `film`, `person`, `list` or `tag`. | ||
| data.results[].uri | string | No | Link to the hit's page on Letterboxd. | |||
| data.results[].year | integer | No | Year the film was released. Present for film hits. | |||
| data.source_url | string | No | URL the data was read from. | |||
| data.type | string | No | Result type the search was limited to, `film`. Omitted for a mixed search. | |||
| msg | string | No | OK |
| Status | Description | Schema |
|---|---|---|
| 400 | Bad Request | #/definitions/app.Response |
| 500 | Internal Server Error | #/definitions/app.Response |
| 503 | Service Unavailable | #/definitions/app.Response |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/letterboxd/search?q=Parasite&type=film&limit=10" \
-H "x-api-key: $CRAWLORA_API_KEY"