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

1. Get user ID first — most queries need it:

   query { me { id username } }
   

2. Query by status — use status_id filter:

   • 1 = Want to Read
   • 2 = Currently Reading
   • 3 = Read
   • 4 = Paused
   • 5 = Did Not Finish

3. 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 |