• Header：

  Authorization: Bearer $WEREAD_API_KEY

• WEREAD_API_KEY

  is obtained from environment variables, in the format

  wrk-xxxxxxxx

• If not set, prompt the user:

  export WEREAD_API_KEY=<your apikey>

• API Key is bound to user identity (vid), interfaces requiring user identity will automatically inject it, no need to manually pass vid

• Method: POST
• Content-Type: application/json
• Body: JSON,

  api_name

  specifies the interface, others are interface parameters,

  skill_version

  must be included in each request

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"}'

• JSON, the response is field-trimmed, only core fields are returned
• Non-zero

  errcode

  indicates an error, with Chinese prompt message
• Send

  {"api_name": "/_list"}

  to view all available interfaces and parameter definitions

1. Version Reporting: Each request body must include

   "skill_version": "1.0.3"

   (take the value of the version field at the top of this file), which is used for the server to check for version updates. If the

   upgrade_info

   field appears in the response, you must immediately pause the current operation, complete the upgrade according to the guidelines in

   upgrade_info.message

   , and re-execute the user request after the upgrade is completed; do not ignore this field
2. Parameter Flattening: Business parameters must be placed at the same level as

   api_name

   and

   skill_version

   ; do not wrap them in objects like

   params

   ,

   data

   , or

   body

   . Only array/object fields explicitly declared in the interface documentation (such as

   reviews

   of

   /book/readreviews

   ) are allowed to be passed as business fields.
3. Pre-check Capability Documentation: Before calling any interface, you must first read the corresponding instruction document according to the "Supported Capabilities" table (e.g., read

   readdata.md

   first for reading statistics,

   shelf.md

   first for bookshelf), confirm interface parameters, field meanings, units, counting calibers and workflows; it is forbidden to guess meanings solely based on field names or experience.
4. Field Interpretation Priority: When interpreting interface responses, take the field descriptions in the corresponding instruction documents as the standard; if the response field name conflicts with intuitive meaning, you must follow the instruction document and not directly translate the field name.
5. bookId Parsing: 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/items are in the bookshelf?", you must calculate it as

   books.length + albums.length + (mp is not null ? 1 : 0)

   ;

   albums[]

   are albums/audiobooks, which also belong to the books in the bookshelf, detailed rules can be found in

   shelf.md

7. Result Display: Use numbered lists for display to facilitate selection; focus on displaying book title, author, and rating for search results; when displaying interface response information, forbid direct translation of fields, and should provide content based on the descriptions in the documents
8. Context Cohesion: Remember the queried bookId in the conversation, and users do not need to provide it repeatedly for subsequent operations
9. Deep Linking: When displaying underlines, thoughts, chapters and other content, splice the corresponding jump links to facilitate users to open the corresponding location directly in the App. For thoughts/reviews, not all have underline positions, only when

   chapterUid

   and

   range

   are available, generate the underline position link
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

      is displayed as "2025-05-30"), raw numbers cannot be displayed directly
    • Reading Duration: Unit is seconds, convert to "X hours Y minutes" format when displayed

weread://reading?bId={bookId}

bookId

bookId

weread://reading?bId=3300045871

• Attach a jump link to each book when displaying the bookshelf list
• Attach an "Open to Read" link when displaying search results
• Provide a "Continue Reading" link when displaying reading progress

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

bookId

bookId

chapterUid

chapters[].chapterUid

/book/chapterinfo

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

• Attach a jump link to each chapter when displaying the chapter catalog

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

bookId

bookId

chapterUid

chapterUid

rangeStart

-

range

rangeEnd

-

range

userVid

/shelf/sync

range Parsing: The

range

field returned by the underline interface is in the format

"start-end"

(e.g.,

"900-2004"

), split it and fill in

rangeStart

and

rangeEnd

respectively.

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

• Attach a jump link to each underline when displaying the underline list (

  /book/bookmarklist

  ) (the

  range

  field can be directly parsed)
• Attach a jump link to each when displaying popular underlines (

  /book/bestbookmarks

  );

  /book/underlines

  is only underline popularity statistics and does not contain underline text
• When displaying thoughts (

  /review/list/mine

  ,

  /book/readreviews

  ), only attach the link to jump to the corresponding underline position if the returned content includes

  chapterUid

  and

  range

  ; reviews for the entire book or reviews that cannot be located to an underline do not require generating this link