weread

WeRead — WeRead Assistant

Call WeRead APIs through Agent API Gateway to provide capabilities such as search, bookshelf, notes, and book reviews.

Supported capabilities

Capability	Description	User example	Detailed description
Search books	Search in the bookstore	"Help me search for The Three-Body Problem"	search.md
Book information	View book details, chapter table of contents, and reading progress	"How many chapters does this book have?" "Where did I read up to?"	book.md
Bookshelf management	View bookshelf	"Take a look at my bookshelf"	shelf.md
Reading statistics	Reading duration, days, preference analysis, reading statistics summary	"How long did I read this month?" "How many books did I read this year?"	readdata.md
Notes and highlights	View personal note count and content, including highlights, thoughts/comments, and bookmark count	"Look at my notes in The Three-Body Problem" "Export my highlights" "How many notes are in this book?"	notes.md
Chapter popular highlights	View popular highlights in a book/chapter, highlight popularity, and thoughts under highlights	"See what popular highlights are in this chapter" "What thoughts are under this passage?"	notes.md
Book reviews	View public reviews of a book	"What reviews does The Three-Body Problem have?" "Look at recommended reviews"	review.md
Recommended books	Personalized recommendations/similar recommendations	"Recommend a few books to me"	discover.md

According to the user's intent, refer to the corresponding description file to understand API parameters, response structure, and workflows.

---

API call specifications

Unified entry point

POST https://i.weread.qq.com/api/agent/gateway

Authentication

• Header：Authorization: Bearer $WEREAD_API_KEY
• WEREAD_API_KEY Obtained from environment variables, format wrk-xxxxxxxx
• If not set, prompt the user:export WEREAD_API_KEY=<你的apikey>
• The API Key is bound to the user identity (vid). APIs that require user identity will automatically inject it, so there is no need to manually pass vid

Request format

• Method：POST
• Content-Type：application/json
• Body：JSON，api_name Specify the API; the rest are API parameters,Every request must include skill_version

curl -X POST "https://i.weread.qq.com/api/agent/gateway" \
  -H "Authorization: Bearer $WEREAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api_name": "/store/search", "keyword": "三体", "count": 10, "skill_version": "1.0.3"}'

Request few-shot

Correct: business parameters are flattened at the top level of the body.

{"api_name":"/user/notebooks","count":100,"skill_version":"1.0.5"}

Correct: the next page continues flattened lastSort。

{"api_name":"/user/notebooks","count":100,"lastSort":1516907353,"skill_version":"1.0.5"}

Incorrect: do not wrap business parameters in params inside.

{"api_name":"/user/notebooks","params":{"count":100,"lastSort":1516907353},"skill_version":"1.0.5"}

The incorrect format above will cause count、lastSort not to be forwarded, and the backend will return the first page according to default values, which appears as if pagination is not working.

Response format

• JSON; responses are field-trimmed and only return core fields
• errcode When non-0, it indicates an error, with a Chinese prompt
• Send {"api_name": "/_list"} to view all available APIs and parameter definitions

General rules

1. Version reporting: every request body must include "skill_version": "1.0.3"(take the value of the version field at the top of this file), used by the server to check for version updates.If upgrade_info field appears in the response, you must immediately pause the current operation and follow the upgrade_info.message guidance to complete the upgrade. After the upgrade is complete, re-execute the user's request. This field must not be ignored
2. Flatten parameters: Business parameters must be placed on the same level as api_name、skill_version ; do not wrap them in params、data、body or other objects. Only array/object fields explicitly declared in the API documentation (such as /book/readreviews 's reviews) are allowed to be passed in as business fields.
3. Capability documentation pre-check: Before calling any API, you must first read the corresponding documentation file based on the "Supported Capabilities" table (e.g., for reading statistics first read readdata.md, for bookshelf first read shelf.md), to confirm the API parameters, field meanings, units, counting criteria, and workflow; it is forbidden to guess meanings based only on field names or experience.
4. Field interpretation priority: When interpreting API responses, the field descriptions in the corresponding documentation file shall prevail; if a response field name conflicts with its intuitive meaning, you must follow the documentation file and must not directly translate the field name.
5. bookId resolution: When the user enters a book title, first call /store/search to obtain the bookId, then perform subsequent operations
6. Bookshelf count: When using /shelf/sync to answer "How many books/entries are on the bookshelf", you must calculate according to books.length + albums.length + (mp 非空 ? 1 : 0) ;albums[] are albums/audiobooks and also count as books on the bookshelf; see shelf.md
7. Result display: Display lists with numbers for easy selection; for search results, focus on displaying book title, author, and rating; when displaying API response information, fieldsmust notbe directly translated; instead, provide them by referring to the descriptions in the documentation
8. Context continuity: Remember the bookId already queried in the conversation, so subsequent operations do not require the user to provide it again
9. Deep links: When displaying content such as highlights, thoughts, and chapters, concatenate the corresponding jump links so users can open them directly in the App; for the specific format, see the "Deep Links (URL Schema)" section below
10. Data display specifications：

• Timestamp: All Unix timestamp fields (such as updateTime、createTime、finishTime、readUpdateTime , etc.),must be converted to YYYY-MM-DD format when displayed(e.g., 1748563200 displayed as "2025-05-30"); the raw number must not be displayed directly
• Reading duration: The unit is seconds; when displaying, convert to the "X hours Y minutes" format

---

Deep Links (URL Schema)

When displaying content such as books, chapters, and highlights, if the response fields are sufficient to construct a link, the corresponding jump link should be attached so that users can click it to open the corresponding location directly in the WeRead App. Thoughts/reviews do not necessarily all have highlight positions; generate a highlight-position link only when both chapterUid and range are present.

Open book (jump to last reading progress)

weread://reading?bId={bookId}

Parameter	Description	Source
bookId	Book ID	Returned by various APIs bookId

Example：

weread://reading?bId=3300045871

Use cases：

• When displaying the bookshelf list, attach a jump link to each book
• When displaying search results, attach an "Open Reading" link
• When displaying reading progress, provide a "Continue Reading" link

Jump to a specified chapter

weread://reading?bId={bookId}&chapterUid={chapterUid}

Parameter	Description	Source
bookId	Book ID	Returned by various APIs bookId
chapterUid	Chapter UID	/book/chapterinfo Returned chapters[].chapterUid

Example：

weread://reading?bId=3300045871&chapterUid=107

Use cases：

• When displaying the chapter list, attach a jump link to each chapter

Jump to the location of the highlight/thought

weread://bestbookmark?bookId={bookId}&chapterUid={chapterUid}&rangeStart={rangeStart}&rangeEnd={rangeEnd}&userVid={userVid}

Parameter	Description	Source
bookId	Book ID	Returned by each API bookId
chapterUid	Chapter UID	The one to which the highlight/thought belongs chapterUid
rangeStart	Highlight start position	range In the field - the number before
rangeEnd	Highlight end position	range In the field - the number after
userVid	User VID	The user ID automatically associated after API Key authentication (obtained from the context of APIs such as /shelf/sync , or omitted)

range parsing: The highlight API returns range in the format "起始-结束"(e.g. "900-2004"), which after splitting is filled into rangeStart and rangeEnd。

Example：

weread://bestbookmark?bookId=3300045871&chapterUid=107&rangeStart=900&rangeEnd=2004&userVid=583802764

Use cases：

• When displaying the highlight list (/book/bookmarklist), attach a jump link to each highlight (therange field can be parsed directly)
• When displaying popular highlights (/book/bestbookmarks), attach a jump link to each one;/book/underlines is only highlight popularity statistics and does not contain the highlight text
• When displaying thoughts (/review/list/mine、/book/readreviews), only attach a link jumping to the corresponding highlight location when the returned content contains chapterUid and range ; for whole-book reviews or comments that cannot be located to a highlight, generating this link is not mandatory