{"openapi":"3.1.0","info":{"title":"Letterboxd API (Bowmark)","version":"e833508f87ff","description":"The social network for film. Reads one film's full record including letterboxd's own weighted average rating over millions of members, the films a member has logged, and a member's diary with their star ratings and full review text — all browserless. Also the library's first provider that can CREATE its own account: signUp drives the real registration form, solves its hCaptcha and verifies the account from the persona's inbox.\n\nEvery function Bowmark has for Letterboxd (letterboxd.com) as one HTTP call. Each runs on Bowmark's infrastructure with the same billing, rules and response envelope as `POST /v1/run`. The whole API: https://api.bowmark.ai/openapi.json. Guide: https://bowmark.ai/docs/api.","contact":{"email":"support@bowmark.ai","url":"https://bowmark.ai/docs/api"}},"servers":[{"url":"https://api.bowmark.ai"}],"security":[{"bearer":[]},{"apiKeyHeader":[]}],"paths":{"/v1/sites/letterboxd/film":{"post":{"operationId":"film","summary":"Reads one film's full record — pass the slug from its letterboxd URL, e.g.","description":"Reads one film's full record — pass the slug from its letterboxd URL, e.g. { slug: \"parasite-2019\" }. Returns title, year, directors, cast, genres, countries, languages, runtime, synopsis and poster, plus `averageRating` (letterboxd's weighted average, 0.5-5), `ratingCount` and `reviewCount`. That rating is computed over millions of member ratings and is published nowhere else.\n\nCalls `bowmark.providers.letterboxd.film`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<LetterboxdFilm>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"type":"object","properties":{"slug":{"type":"string"}},"required":["slug"],"additionalProperties":true,"description":"TypeScript: `{ slug: string }`"}},"required":["args"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/letterboxd/memberFilms":{"post":{"operationId":"memberFilms","summary":"Lists the films a member has logged, newest first — { member: \"davidehrlich\" }, with `limit` capping rows (default 72, max 200).","description":"Lists the films a member has logged, newest first — { member: \"davidehrlich\" }, with `limit` capping rows (default 72, max 200). Returns slug, title, year and URL per film, which is what `film` takes to go deeper on any one of them.\n\nCalls `bowmark.providers.letterboxd.memberFilms`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<LetterboxdMemberFilm[]>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"type":"object","properties":{"member":{"type":"string"},"limit":{"type":"number"}},"required":["member"],"additionalProperties":true,"description":"TypeScript: `{ member: string, limit?: number }`"}},"required":["args"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/letterboxd/memberDiary":{"post":{"operationId":"memberDiary","summary":"Reads a member's activity feed: every film they logged, with their own star rating, the date they watched it, whether it was a rewatch, whether they liked it, and the full text of any review they wrot","description":"Reads a member's activity feed: every film they logged, with their own star rating, the date they watched it, whether it was a rewatch, whether they liked it, and the full text of any review they wrote. The review prose is the part no listing page carries. List and like activity is skipped.\n\nCalls `bowmark.providers.letterboxd.memberDiary`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<LetterboxdDiaryEntry[]>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"type":"object","properties":{"member":{"type":"string"},"limit":{"type":"number"}},"required":["member"],"additionalProperties":true,"description":"TypeScript: `{ member: string, limit?: number }`"}},"required":["args"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/letterboxd/getOwnAccount":{"post":{"operationId":"getOwnAccount","summary":"Reads WHO is signed in on the saved letterboxd login: the account's username, its membership role and its profile URL.","description":"Reads WHO is signed in on the saved letterboxd login: the account's username, its membership role and its profile URL. Signed-in only (it pauses the run for a sign-in when there is none), and a stale session throws rather than returning an empty account.\n\nCalls `bowmark.providers.letterboxd.getOwnAccount`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<LetterboxdAccount>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"opts":{"type":"object","properties":{"connection":{"type":"string"}},"required":["connection"],"additionalProperties":true,"description":"TypeScript: `ConnectionOption`"}},"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/letterboxd/login":{"post":{"operationId":"login","summary":"Signs in with the given credentials and saves a NEW connection — every call creates one, never replacing an existing login, unless `connection` names an existing id to sign back in to (its cookies rep","description":"Signs in with the given credentials and saves a NEW connection — every call creates one, never replacing an existing login, unless `connection` names an existing id to sign back in to (its cookies replaced, its id and settings kept, a logged-out one revived). The returned `connection` is usable on the very next call in the same script or session. `warnings` names the account's other connections to this site. `username`, `password`, `totpCode` and `totpSeed` are plain values here; a caller on the run/session script surface instead passes each as a `bowmark.secret()` reference. Pass the returned `connection` id as `{ connection }` on a later signed-in call to act as this account. Optionally set `keepAlive: { everyHours }` (or `false` to turn it off) and/or `expiresAt` (an ISO date/datetime, a hard ceiling); both default to a 12-hour keep-alive and can be changed later with `bm.connections.update(id, …)`.\n\nCalls `bowmark.providers.letterboxd.login`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<{ connection: string; account: string; expiresAt: string; warnings?: string[] }>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"creds":{"type":"object","properties":{"username":{"type":"string"},"password":{"type":"string"},"totpCode":{"type":"string"},"totpSeed":{"type":"string"},"keepAlive":{"anyOf":[{"type":"object","properties":{"everyHours":{"type":"number"}},"required":["everyHours"],"additionalProperties":true},{"const":false}]},"expiresAt":{"type":"string"},"connection":{"type":"string"}},"additionalProperties":true,"description":"TypeScript: `LoginInput`"}},"required":["creds"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/letterboxd/signup":{"post":{"operationId":"signup","summary":"Makes a NEW Letterboxd account with the person's own email and password, in a session.","description":"Makes a NEW Letterboxd account with the person's own email and password, in a session. Pauses with `needs_code` / `needs_phone` whenever the site wants something only the person has; continue with `confirmSignup` in the same session. Ends `signed_up` with the login saved and the credentials in the person's secrets.\n\nCalls `bowmark.providers.letterboxd.signup`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<{ status: \"needs_code\"; channel: \"email\" | \"sms\"; sentTo?: string } | { status: \"needs_phone\" } | { status: \"in_progress\"; retryAfterSeconds: number } | { status: \"signed_up\"; username: string; email: string; connection: string | null; twoFactor: \"enrolled\" | \"none\"; secrets: string[] }>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"description":"TypeScript: `SignupInput`"}},"required":["args"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/letterboxd/confirmSignup":{"post":{"operationId":"confirmSignup","summary":"Continues the sign-up `signup` started in this session with the emailed or texted `code`, the email's verification `link`, or the person's `phone`.","description":"Continues the sign-up `signup` started in this session with the emailed or texted `code`, the email's verification `link`, or the person's `phone`.\n\nCalls `bowmark.providers.letterboxd.confirmSignup`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<{ status: \"needs_code\"; channel: \"email\" | \"sms\"; sentTo?: string } | { status: \"needs_phone\" } | { status: \"in_progress\"; retryAfterSeconds: number } | { status: \"signed_up\"; username: string; email: string; connection: string | null; twoFactor: \"enrolled\" | \"none\"; secrets: string[] }>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"description":"TypeScript: `SignupConfirmInput`"}},"required":["args"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Your Bowmark API key."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-Bowmark-Key"}},"responses":{"NotFound":{"description":"No such site or function.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}},"schemas":{"RunEnvelope":{"type":"object","description":"What a run returns. `status` says whether the SCRIPT succeeded. A script that threw or paused for a login is still HTTP 200. Branch on `status`, not on the HTTP code.","required":["ok","status","result","logs","error","ms"],"properties":{"runId":{"type":"string","description":"Stable id for this run. Quote it in a support or `report` message."},"ok":{"type":"boolean","description":"False only when the run produced nothing usable."},"status":{"type":"string","enum":["ok","error","partial","needs_user"],"description":"`partial`: the result is real but some calls failed (see `incomplete`); `ok` stays true. `needs_user`: a person must sign in to a site first. Relay `meta.handoff.url` to them, then run again."},"egress":{"type":"string","enum":["default","link"],"description":"The egress the run was given, present only when the request asked for one. `link`: every request went through the caller's own Chrome (Bowmark Buddy)."},"result":{"description":"Whatever the script `return`ed. Any JSON value."},"logs":{"type":"array","items":{"type":"string"},"description":"Lines the script wrote with `log(...)`."},"error":{"type":["string","null"],"description":"Why the run failed, in plain words. Null on success."},"ms":{"type":"integer","description":"How long the script itself ran, in milliseconds."},"queuedMs":{"type":"integer","description":"How long the run waited for a worker before starting. Present only when it was a second or more."},"needs":{"type":"array","description":"The sign-ins this script is waiting on. Present when `status` is `needs_user`.","items":{"type":"object","required":["capability","provider","providerTitle","kind"],"properties":{"capability":{"type":"string"},"provider":{"type":"string"},"providerTitle":{"type":"string","description":"The site's name, to show a person."},"kind":{"type":"string"}}}},"incomplete":{"type":"object","description":"Present only when `status` is `partial`: which calls did not answer.","properties":{"summary":{"type":"string"},"totalCalls":{"type":"integer"}},"additionalProperties":true},"emptyHanded":{"type":"object","description":"Present when the script returned nothing while its calls returned rows, usually a filter that matched none of the site's own labels. Lists the label values the calls actually returned.","additionalProperties":true},"notes":{"type":"array","description":"Caveats a call attached to a complete answer. Never changes `status`.","items":{"type":"object","properties":{"path":{"type":"string"},"notes":{"type":"array","items":{"type":"string"}}}}},"meta":{"type":"object","properties":{"handoff":{"type":"object","description":"A single-use sign-in link for a person to open. Expires at `expiresAt`.","properties":{"ref":{"type":"string"},"url":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time"}}},"concurrency":{"type":"object","description":"On a 429: how many runs are in flight and when to retry.","properties":{"limit":{"type":"integer"},"inFlight":{"type":"integer"},"retryAfterSeconds":{"type":"integer"}}}},"additionalProperties":true},"notice":{"type":"object","description":"Set when the account owner has not accepted the current Terms. Relay it to them.","additionalProperties":true}}}}}}