sampaiodev.
PTEN
Automation APIOpen-source

notebooklm-api

Turns NotebookLM flows into a programmable surface: REST, CLI and server-rendered UI, with multi-account support.

FastAPICLIWeb UIMulti-accountPlaywright/storage state

Technical reading

Quick case read

Problem

NotebookLM is useful in the UI, but repeated flows need an API, account selection, session checks and clear limits when Google asks for a challenge.

Solution

The app exposes REST, CLI and a web UI, selects accounts through `X-NotebookLM-Account-Id`, isolates `storage_state` and protects sensitive routes with default-deny Bearer authentication.

Stack

FastAPI · CLI · Web UI · Multi-account

Status

Open-source

Architecture

An API around web sessions with per-account isolation

Each account keeps its own `storage_state`. Jobs and artifacts honor account scope, and cross-account access returns 404 without revealing whether the resource exists.

Technical flow

  • Input
  • Processing
  • Storage
  • Output
Flowchart
Rendering flowchart…

Step-by-step flow

01Input
REST/CLI/UI clientHTTP request, CLI or server-rendered UI
02API
FastAPIAccount and automation routes
03Selection
AccountX-NotebookLM-Account-Id header or default
04Session
storage_statePer-account isolated cookies/storage state
05Automation
NotebookLM/browserProgrammatic web flow
06Result
Download/artifactGenerated file or output
07Output
HTTP/API responseProgrammatic return
Diagram source (Mermaid)
Paste into any Mermaid renderer
flowchart LR
  client["REST/CLI/UI client"]
  api["FastAPI"]
  account["Account"]
  state["storage_state"]
  browser["NotebookLM/browser"]
  artifact["Download/artifact"]
  response["HTTP/API response"]
  client --> api
  api --> account
  account --> state
  state --> browser
  browser --> artifact
  artifact --> response
1. REST/CLI/UI client (Input) → FastAPI. 2. FastAPI (API) → Account. 3. Account (Selection) → storage_state. 4. storage_state (Session) → NotebookLM/browser. 5. NotebookLM/browser (Automation) → Download/artifact. 6. Download/artifact (Result) → HTTP/API response. 7. HTTP/API response (Output).

Stack and responsibilities

  • FastAPI

    REST API and server-rendered web UI.

  • CLI

    Programmatic operation outside the browser.

  • storage_state.json

    Per-account session persistence.

  • Bearer + account scoping

    Default-deny auth and isolation for jobs, artifacts and sessions.

Technical decisions

  • Multi-account without mixing sessions

    Each account gets its own `storage_state`, and resources are queried within the selected scope.

  • Default-deny

    Without a token and outside local insecure mode, sensitive routes return 401.

  • Honest limitation

    A web session is not eternal: challenge, 2FA or expiration require manual renewal.

Operations

  • documentedPer-account status

    healthy, warming, degraded, challenge_required, expired, disabled.

  • documentedAuth and CORS

    Bearer is required in production and CORS is closed by default.

  • documentedPublic tests

    Tests cover isolation, scoping, errors, auth and the account contract.

Status and next steps

  • Strengthen renewal UX when Google requires a challenge.
  • Document concurrency limits per real flow.

Contact

Want something similar for your process?

If there is repeated input, a manual step and an expected output, there is probably a system to design.

Talk about a project