WeRead (Official Agent Gateway)

May 18, 2026 Β· View on GitHub

Mode: 🌐 Public · Domain: weread.qq.com

Pure HTTP adapter against WeRead's official Agent Gateway (https://i.weread.qq.com/api/agent/gateway). Coexists with the cookie-driven weread adapter β€” pick whichever auth model the operator has.

Commands

CommandDescription
opencli weread-official search <keyword>Search the WeRead store via /store/search (9 scope codes)
opencli weread-official shelfSync your shelf β€” books, albums, and the 文章攢藏 (article) entry
opencli weread-official book <bookId>Book metadata + chapter list + reading progress (3-in-1)
opencli weread-official notes [bookId]Notebook overview, or merged highlights + thoughts for a specific book
opencli weread-official review <bookId>Browse public reviews of a book
opencli weread-official readdataReading statistics: time, streak, preferences, top books
opencli weread-official discover [bookId]Personalized recommendations (no bookId) or similar books (with bookId)
opencli weread-official list-apisList every api_name supported by the gateway (meta endpoint)

Usage Examples

# Search
opencli weread-official search "三体"
opencli weread-official search "εˆ˜ζ…ˆζ¬£" --scope author --count 20
opencli weread-official search "AI" --scope ebook --max-idx 20   # next page

# Shelf β€” books + albums + article-bookmark entry
opencli weread-official shelf

# Book detail (info + chapters + progress)
opencli weread-official book 3300045871
opencli weread-official book 3300045871 --no-chapters   # skip chapter list
opencli weread-official book 3300045871 --no-progress   # skip reading progress

# Notebook overview (all books you've annotated)
opencli weread-official notes
opencli weread-official notes --last-sort 1748563200    # next page cursor

# Merged highlights + thoughts for a specific book
opencli weread-official notes 3300045871

# Public reviews of a book
opencli weread-official review 3300045871
opencli weread-official review 3300045871 --type recommend --count 20
opencli weread-official review 3300045871 --type newest

# Reading statistics
opencli weread-official readdata --mode weekly
opencli weread-official readdata --mode monthly
opencli weread-official readdata --mode annually
opencli weread-official readdata --mode overall
opencli weread-official readdata --mode weekly --base-time 1748563200

# Discover β€” personalized recommendations
opencli weread-official discover --count 20

# Discover β€” books similar to a given one
opencli weread-official discover 3300045871 --count 20

# Meta β€” list every gateway endpoint
opencli weread-official list-apis

# JSON output (useful for piping into other tools)
opencli weread-official book 3300045871 -f json

Search Scopes

--scopeCodeMeaning
all (default)0All categories
ebook10E-books only
webnovel16Web novels
audio14Audiobooks
author6Author profiles
fulltext12Full-text search inside books
booklist13Curated book lists
mp2WeChat Official Account subscriptions
article4Individual articles

Review Types

--typeCodeMeaning
all (default)0All reviews
recommend1Recommended reviews
thumbs-down2Negative reviews
newest3Most recent reviews
neutral4Neutral reviews

Reading Stat Modes

weekly, monthly, annually, overall. Optional --base-time <unix-seconds> shifts the period anchor.

Output Columns

CommandColumns
searchrank, scope, bookId, title, author, rating, readingCount, category, searchIdx, cover, intro, link
shelfrank, kind, bookId, title, author, rating, finishReadingTime, readingTime, progress, secret, link
booksection, bookId, title, value, ... (rows tagged info / chapter / progress)
notes`kind, bookId, title, count
reviewrank, reviewId, bookId, userName, star, content, likedCount, commentCount, time, link
readdatasection, label, value (sections: summary, longest, readStat, preferCategory, preferAuthor, preferPublisher, preferTime)
discoverrank, mode, bookId, title, author, rating, readingCount, category, idx, reason, cover, intro, link
list-apisrank, apiName, description, required, optional, extras (last row: (client) SKILL_VERSION=...)

Notes

  • Bearer auth only. All commands require WEREAD_API_KEY (format wrk-*) exported in the environment. The adapter refuses to call the gateway when the key is missing.
  • No browser, no cookies. Pure HTTP β€” works in containers / CI / headless servers without a Chrome dependency.
  • mp entry on the shelf represents the user's WeChat Official Account / article bookmark feed. Shelf count formula: books.length + albums.length + (mp非空 ? 1 : 0).
  • Rating tiers: η₯žδ½œ β‰₯90%, εŠ›θ β‰₯80%, ε₯½θ―„ β‰₯70%, otherwise X.Xεˆ† (raw 0-1000 scale rendered as a percentage).
  • Star field uses multiples of 20: 20=⭐, 40=⭐⭐, ..., 100=⭐⭐⭐⭐⭐. -1 and 0 both mean "no rating".
  • readdata preferTime is a 24-hour rotation starting at 06:00, mirroring the official SKILL output.
  • Deep links in the link column use the weread:// URI scheme β€” clickable on devices with the WeRead app installed.
  • Errors are typed:
    • Missing key / blank env var β†’ AuthRequiredError (refuses to call the gateway).
    • errcode -2010 / -2012 β†’ AuthRequiredError (token rejected by gateway).
    • upgrade_info in response β†’ CommandExecutionError naming both required and current skill_version.
    • HTTP non-2xx, invalid JSON, timeout, or any non-zero errcode β†’ CommandExecutionError / TimeoutError.
    • Empty result sets β†’ EmptyResultError (never silent [], never sentinel rows).

Prerequisites

  • No browser required β€” pure HTTP gateway calls.

  • Export an API key obtained from the official WeRead agent-skill program:

    export WEREAD_API_KEY=wrk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

  • Skill version is pinned to 1.0.3 and reported with every request. When the gateway returns upgrade_info, pull the latest weread-skills.zip and bump SKILL_VERSION in clis/weread-official/utils.js.

  • weread β€” Cookie + browser adapter for the reverse-engineered private endpoints. Use this when you don't have an official API key.