Skills hardcover

Name: hardcover
Author: openclaw

Query 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

source · Clone the upstream repo

git clone https://github.com/openclaw/skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/asaphko/hardcover" ~/.claude/skills/openclaw-skills-hardcover && rm -rf "$T"

OpenClaw · Install into ~/.openclaw/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.openclaw/skills && cp -r "$T/skills/asaphko/hardcover" ~/.openclaw/skills/openclaw-skills-hardcover && rm -rf "$T"

manifest: skills/asaphko/hardcover/SKILL.md

Hardcover GraphQL API

Query your reading library, book metadata, and search Hardcover's catalog.

Configuration

Env variable:
```
HARDCOVER_API_TOKEN
```
from https://hardcover.app/settings
Endpoint:
```
https://api.hardcover.app/v1/graphql
```
Rate limit: 60 req/min, 30s timeout, max 3 query depth

Authentication

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

Workflow

Get user ID first — most queries need it:

query { me { id username } }

Query by status — use
```
status_id
```
filter:
- ```
1
```
  = Want to Read
- ```
2
```
  = Currently Reading
- ```
3
```
  = Read
- ```
4
```
  = Paused
- ```
5
```
  = Did Not Finish
Paginate large results — use
```
limit
```
/
```
offset
```
, add
```
distinct_on: book_id
```

Common Queries

Currently Reading with Progress

query {
  me {
    user_books(where: { status_id: { _eq: 2 } }) {
      user_book_reads { progress_pages }
      book {
        title
        pages
        image { url }
        contributions { author { name } }
      }
    }
  }
}

Library by Status

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

Search Books/Authors/Series

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

Book Details by Title

query {
  editions(where: { title: { _eq: "Oathbringer" } }) {
    title
    pages
    isbn_13
    edition_format
    publisher { name }
    book {
      slug
      contributions { author { name } }
    }
  }
}

Limitations

Read-only (no mutations yet)
No text search operators (
```
_like
```
,
```
_ilike
```
,
```
_regex
```
)
Access limited to: your data, public data, followed users' data
Tokens expire after 1 year

Entity Reference

For detailed field documentation on Books, Editions, Authors, Series, User Books, Activities, Lists, Goals, and other entities, see references/entities.md.

Response Codes

Code	Meaning
200	Success
401	Invalid/expired token
429	Rate limited