Lists

Last Updated   August 3, 2025

Reference

What Is a List?

Lists in Hardcover are user-created collections of books organized around themes, genres, or personal preferences. Users can create public or private lists to organize and share their reading recommendations with the community.

Queries

Available List Queries

Query	Returns	Description
lists	lists[]	Fetch an array of lists with filtering and pagination
lists_aggregate	lists_aggregate	Get aggregated data about lists (count, averages, etc.)
lists_by_pk	lists	Fetch a single list by its primary key (id)
list_books	list_books[]	Fetch books in lists with filtering options
list_books_aggregate	list_books_aggregate	Get aggregated data about books in lists
list_books_by_pk	list_books	Fetch a single list book entry by its id
followed_lists	followed_lists[]	Fetch lists followed by users
followed_lists_by_pk	followed_lists	Fetch a single followed list entry by id

List Schema Fields

Field	Type	Description
id	int	Unique identifier for the list
name	string	The title/name of the list
description	string	Description of the list’s purpose or theme
slug	string	URL-friendly identifier for the list
books_count	int	Total number of books in the list
likes_count	int	Number of users who have liked this list
public	bool	Whether the list is publicly visible
privacy_setting_id	int	Privacy setting for the list: 1 = public, 2 = followers only, 3 = private
user_id	int	ID of the user who created the list
created_at	timestamp	When the list was created
updated_at	timestamp	When the list was last modified
user	User	User object of the list creator
list_books	ListBook[]	Array of books associated with this list

ListBook Schema Fields

Field	Type	Description
id	int	Unique identifier for the list_book entry
list_id	int	ID of the list containing this book
book_id	int	ID of the book in this list
edition_id	int	Optional specific edition of the book
position	int	Order position of the book in the list
date_added	timestamptz	When the book was added to the list
book	books	The book object
list	lists	The list object
edition	editions	Optional edition object

Related Schemas

• Books - Books that can be added to lists
• Users - Users who create and interact with lists
• Editions - Specific editions of books

Example Queries

Get All Public Lists

Retrieve the top 10 most-liked public lists.

Query

Public Lists

query GetPublicLists {
  lists(
      where: {public: {_eq: true}}
      order_by: {likes_count: desc}
      limit: 10
  ) {
      id
      name
      description
      books_count
      likes_count
      user {
          username
      }
  }
}

Try it yourself

Get Lists by a Specific User

Get all lists created by a specific user. Replace ##USER_ID## with the actual user ID.

Query

User Lists

query GetUserLists {
  lists(
      where: {user_id: {_eq: ##USER_ID##}},
      order_by: {updated_at: desc}
  ) {
      id
      name
      description
      books_count
      public
      created_at
      updated_at
  }
}

Get Books in a Specific List

Get all books in a specific list with their details.

This example uses NPR Top 100 Science Fiction Fantasy list (ID: 3).

Note

The list must be public or owned by the authenticated user.

Query

List Books

query GetListBooks {
  lists(where: {id: {_eq: 3}}) {
      name
      description
      list_books {
          book {
              id
              title
              contributions {
                  author {
                      name
                  }
              }
              rating
              pages
          }
          position
          date_added
      }
  }
}

Try it yourself

Get a Single List by ID

Fetch a specific list using its primary key.

Query

Get List by ID

query GetListById {
  lists_by_pk(id: 3) {
      id
      name
      description
      books_count
      likes_count
      privacy_setting_id
      created_at
      updated_at
      user {
          id
          username
          image_id
      }
  }
}

Try it yourself

Get List Statistics

Use aggregate queries to get statistics about lists.

Query

List Statistics

query GetListStats {
  lists_aggregate(where: {public: {_eq: true}}) {
      aggregate {
          count
          avg {
              books_count
              likes_count
          }
          max {
              books_count
              likes_count
          }
      }
  }
}

Try it yourself

Get Followed Lists

Get all lists that the authenticated user is following.

Query

Followed Lists

query GetMyFollowedLists {
  followed_lists(order_by: {created_at: desc}) {
      id
      created_at
      list {
          id
          name
          description
          books_count
          likes_count
          user {
              username
          }
      }
  }
}

Try it yourself

Get Lists by Popularity

Find public lists ordered by popularity.

Note

The Hardcover API doesn’t support text search operators like _ilike for lists. Use exact matches or browse public lists by popularity.

Query

Popular Lists

query GetPopularLists {
  lists(
      where: {public: {_eq: true}}
      limit: 20
      order_by: {likes_count: desc}
  ) {
      id
      name
      description
      books_count
      likes_count
      user {
          username
      }
  }
}

Try it yourself

Mutations

Available List Mutations

Mutation	Returns	Description
insert_list	ListIdType	Create a new list
update_list	ListIdType	Update an existing list
delete_list	ListDeleteType	Delete a list (must be owner)
insert_list_book	ListBookIdType	Add a book to a list
delete_list_book	ListBookDeleteType	Remove a book from a list
update_list_books	list_books_mutation_response	Update multiple list book entries
upsert_followed_list	FollowedListType	Follow or unfollow a list
delete_followed_list	DeleteListType	Unfollow a list

Mutation Response Types

List mutations return different response types based on the operation:

ListIdType (for insert_list, update_list)

Field	Type	Description
id	Int	ID of the created/updated list
list	lists	The complete list object
errors	String	Any error messages

ListBookIdType (for insert_list_book)

Field	Type	Description
id	Int	ID of the created list_book entry
list_book	list_books	The complete list_book object

ListDeleteType (for delete_list) and DeleteListType (for delete_followed_list)

Field	Type	Description
success	Boolean!	Whether the deletion was successful

Create a New List

Create a new list with name, description, and privacy setting.

Privacy settings:

• 1 = public
• 2 = followers only
• 3 = private

Note

New lists may take a few minutes to appear on the website due to caching.

Query

Create List

mutation CreateList {
  insert_list(
      object: {
          name: "My Favorite Sci-Fi Books"
          description: "A collection of the best science fiction novels I've read"
          privacy_setting_id: 1
      }
  ) {
      affected_rows
      returning {
          id
          name
          description
          public
          created_at
          user {
              username
          }
      }
  }
}

Add a Book to a List

Add a book to your own list.

Note

You can only add books to lists you own. The position field determines the order of books in the list.

Query

Add Book to List

mutation AddBookToList {
  insert_list_book(
      object: {
          list_id: 27818
          book_id: 456
          position: 1
      }
  ) {
      id
      list_book {
          id
          list_id
          book_id
          position
          date_added
          book {
              title
          }
          list {
              name
          }
      }
  }
}

Update a List

Update an existing list’s details.

Note

You can only update lists you own. The object parameter accepts the same fields as when creating a list.

Query

Update List

mutation UpdateList {
  update_list(
      id: 27818
      object: {
          name: "Updated List Name"
          description: "This is the updated description for my list"
          privacy_setting_id: 2
      }
  ) {
      id
      list {
          id
          name
          description
          privacy_setting_id
          updated_at
      }
  }
}

Delete a List

Delete a list you own.

Caution

This action is irreversible. All books in the list will be removed as well.

Query

Delete List

mutation DeleteList {
  delete_list(id: 27818) {
      success
  }
}

Remove a Book from a List

Remove a specific book from your list.

Query

Remove Book from List

mutation RemoveBookFromList {
  delete_list_book(id: 123456) {
      id
      list_id
      list {
          name
          books_count
      }
  }
}

Follow/Unfollow a List

Follow a public list to track updates. This mutation acts as an upsert - it will create a follow if it doesn’t exist.

Query

Follow List

mutation FollowList {
  upsert_followed_list(list_id: 3) {
      id
      followed_list {
          id
          list_id
          user_id
          created_at
          list {
              name
              user {
                  username
              }
          }
      }
  }
}

Unfollow a List

Remove a list from your followed lists.

Query

Unfollow List

mutation UnfollowList {
  delete_followed_list(list_id: 3) {
      success
  }
}