hardcoverQuery reading lists and book data from Hardcover.app via GraphQL API. Triggers when user mentions Hardcover, asks about their reading list/library, wants book progress, searches for books/authors/series, or references "currently reading", "want to read", or "books I've read". Also use for syncing reading data to other systems (Obsidian, etc.) or tracking reading goals.
Install via ClawdBot CLI:
clawdbot install asaphko/hardcoverQuery your reading library, book metadata, and search Hardcover's catalog.
HARDCOVER_API_TOKEN from https://hardcover.app/settingshttps://api.hardcover.app/v1/graphqlAll queries require Authorization: Bearer {token} header (token from settings, add Bearer prefix):
curl -X POST https://api.hardcover.app/v1/graphql \
-H "Authorization: Bearer $HARDCOVER_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"query": "query { me { id username } }"}'
query { me { id username } }status_id filter:1 = Want to Read2 = Currently Reading 3 = Read4 = Paused5 = Did Not Finishlimit/offset, add distinct_on: book_idquery {
me {
user_books(where: { status_id: { _eq: 2 } }) {
user_book_reads { progress_pages }
book {
title
pages
image { url }
contributions { author { name } }
}
}
}
}query ($userId: Int!, $status: Int!) {
user_books(
where: { user_id: { _eq: $userId }, status_id: { _eq: $status } }
limit: 25
offset: 0
distinct_on: book_id
) {
book {
id
title
pages
image { url }
contributions { author { name } }
}
}
}query ($q: String!, $type: String!) {
search(query: $q, query_type: $type, per_page: 10, page: 1) {
results
}
}query_type: Book, Author, Series, Character, List, Publisher, User
query {
editions(where: { title: { _eq: "Oathbringer" } }) {
title
pages
isbn_13
edition_format
publisher { name }
book {
slug
contributions { author { name } }
}
}
}_like, _ilike, _regex)For detailed field documentation on Books, Editions, Authors, Series, User Books, Activities, Lists, Goals, and other entities, see references/entities.md.
| Code | Meaning |
|------|---------|
| 200 | Success |
| 401 | Invalid/expired token |
| 429 | Rate limited |
Generated Mar 1, 2026
Users can query their reading lists by status (currently reading, want to read, read) to track progress and set goals. This helps individuals monitor their reading habits and visualize achievements over time, enhancing personal accountability and motivation.
Users search for books, authors, or series to find new reads based on interests or recommendations. This supports readers in expanding their libraries and making informed choices, useful for book clubs or academic purposes.
Integrate reading data with external systems like Obsidian to sync book progress and metadata. This enables users to maintain organized notes or journals linked to their reading activities, streamlining knowledge management.
Access public or followed users' data to compare reading habits and discover trends. This fosters community engagement and shared recommendations, beneficial for social platforms or reading groups.
Authors or publishers query book details, editions, and contributions to manage metadata or track their works. This aids in cataloging and promotional efforts, supporting content creators in the publishing industry.
Offer tiered subscription plans for enhanced API features, such as higher rate limits or advanced search capabilities. Revenue is generated from developers or businesses integrating the skill into their applications, ensuring sustainable service maintenance.
Provide aggregated, anonymized reading data to publishers or marketers for market research and trend analysis. Revenue comes from licensing these insights to help optimize book promotions and target audiences effectively.
Collaborate with productivity tools, educational platforms, or social apps to embed reading tracking features. Revenue is generated through partnership agreements, referral fees, or revenue-sharing models based on user engagement.
💬 Integration Tip
Always start by querying the user ID with the me endpoint, as most operations depend on it, and handle pagination for large datasets to avoid performance issues.
Work with Obsidian vaults (plain Markdown notes) and automate via obsidian-cli.
Create, search, and manage Bear notes via grizzly CLI.
Track water and sleep with JSON file storage
Notion API for creating and managing pages, databases, and blocks.
Smart ClawdBot documentation access with local search index, cached snippets, and on-demand fetch. Token-efficient and freshness-aware.
Work with Obsidian vaults as a knowledge base. Features: fuzzy/phonetic search across all notes, auto-folder detection for new notes, create/read/edit notes with frontmatter, manage tags and wikilinks. Use when: querying knowledge base, saving notes/documents, editing existing notes by user instructions.