Call WeRead interfaces through the Agent API Gateway, providing 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 the number and content of personal notes, including highlights, thoughts/comments, and bookmark counts | "Take a look at my notes in The Three-Body Problem" "Export my highlights" "How many notes are there in this book" | notes.md |
| Popular chapter highlights | View popular highlights for a book/chapter, highlight popularity, and thoughts under highlights | "Take a look at what popular highlights this chapter has" "What thoughts are under this passage" | notes.md |
| Book reviews | View public reviews of a book | "What reviews does The Three-Body Problem have?" "Take a look at recommended reviews" | review.md |
| Recommended good books | Personalized recommendations/similar recommendations | "Recommend a few books to me" | discover.md |
Based on the user's intent, refer to the corresponding documentation file to understand interface parameters, response packet structure, and workflows.
Interface calling specification
Unified entry point
POST https://i.weread.qq.com/api/agent/gateway
Authentication
- Header:
Authorization: Bearer $WEREAD_API_KEY WEREAD_API_KEYObtained from environment variables, formatwrk-xxxxxxxx- If not set, prompt the user:
export WEREAD_API_KEY=<你的apikey> - The API Key is bound to the user identity (vid). Interfaces 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_nameSpecify the interface; the rest are interface parameters,Every request must includeskill_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.5"}'
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: continue flattening on the next page 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 usage above will cause count、lastSort not to be forwarded, and the backend will return the first page according to the default value, making it look like pagination is broken.
Response format
- JSON; the response packet has undergone field trimming and only returns core fields
errcodeWhen non-0, it indicates an error; provide a Chinese prompt- Send
{"api_name": "/_list"}to view all available interfaces and parameter definitions
General rules
- Version reporting: every request body must include
"skill_version": "1.0.5"(take the value of the version field at the top of this file), used by the server to check for version updates.If the response packet contains theupgrade_infofield, you must immediately pause the current operation and follow theupgrade_info.messageinstructions to complete the upgrade. After the upgrade is complete, re-execute the user's request. This field must not be ignored - Flat parameters: Business parameters must be placed at the same level as
api_name、skill_version; do not wrap them inparams、data、bodyor other objects. Only array/object fields explicitly declared in the API documentation (such as/book/readreviewsinreviews) are allowed to be passed in as business fields. - Capability documentation pre-check: Before calling any API, you must first read the corresponding documentation file according to the "Supported Capabilities" table (for example, for reading statistics first read
readdata.md, for bookshelf first readshelf.md), to confirm the API parameters, field meanings, units, counting calibers, and workflows; it is forbidden to guess meanings based solely on field names or experience. - Field interpretation priority: When interpreting API responses, the field descriptions in the corresponding documentation file shall prevail; if a response field name conflicts with the intuitive meaning, you must follow the documentation file and must not directly translate the field name.
- bookId parsing: When the user inputs a book title, first call
/store/searchto obtain the bookId, then perform subsequent operations - Bookshelf quantity: When using
/shelf/syncto answer "how many books/how many items are on the bookshelf", you must calculate according tobooks.length + albums.length + (mp 非空 ? 1 : 0);albums[]are albums/audiobooks, which also count as books on the bookshelf; for detailed rules seeshelf.md - 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, fieldsare forbiddento be directly translated; instead, provide the described content from the documentation
- Context continuity: Remember the bookId that has been queried during the conversation; subsequent operations do not require the user to provide it again
- Book jump link: Prefer using the
readerLinkfrom the API response as the direct reader link, displayed as[打开阅读]({readerLink}); when there is noreaderLinkbut there isdeepLink, displaydeepLinkas[查看详情]({deepLink}); when neither field is present, do not construct a link yourself - Data display specification:
- Timestamp: All Unix timestamp fields (such as
updateTime、createTime、finishTime、readUpdateTime, etc.),must be converted to YYYY-MM-DD format when displayed(for example,1748563200is displayed as "2025-05-30"); the raw number must not be displayed directly - Reading duration: The unit is seconds; when displayed, convert to the "X hours Y minutes" format
Book jump link
When displaying books, chapters, highlights, thoughts, and other content, directly use the link fields from the API response; do not construct URLs yourself.
- When the response has
readerLink, display as[打开阅读]({readerLink})。 - When the response does not have
readerLinkbut hasdeepLink, display as[查看详情]({deepLink})。 - When both fields exist, return
readerLinkfirst; only additionally displaydeepLink。 - when the user needs the book details entry; when neither field exists, do not attempt to manually construct
weread://orhttps://weread.qq.com/links.