---
title: "List books"
method: GET
path: "/api/v1/books"
tags: ["Books"]
---

# List books

`GET /api/v1/books`

## Request

- Base URL: `https://beyourcover.com`
- URL: `https://beyourcover.com/api/v1/books`
- Auth: HTTP bearer

Lists books owned by the API key's account, newest first, with keyset cursor pagination. Hidden books stay out unless `include_hidden=true`, as on the dashboard shelf. Each book carries its cover count and its shelf thumbnail (`thumbnail_cover_id`).

## Query parameters

- `limit` integer
- `cursor` string
- `q` string
- `include_hidden` boolean
- `source_type` 'generated' | 'external_wrap' | 'premade'

## Response `200`

One page of books.

- BookList
  - `books` BookSummary[], required: Newest first.
    - `bookId` string, uuid, required
    - `title` string, required
    - `author` string, nullable
    - `subtitle` string, nullable
    - `genre` string, required: Canonical genre value (e.g. `Science Fiction`).
    - `subgenre` string, nullable
    - `summary` string, nullable
    - `target_audience` string, nullable
    - `planner_year` string, nullable: Planner & Journal books only: the year on the cover.
    - `visibility` 'default' | 'hidden', required: `hidden` books are off the dashboard shelf and out of `GET /api/v1/books` unless `include_hidden=true`.
    - `source_type` 'generated' | 'external_wrap' | 'premade', required: `generated` = made in the generator or the API; `external_wrap` = an uploaded cover (External Cover Studio); `premade` = a bought premade cover.
    - `thumbnail_cover_id` string, uuid, nullable, required: The coverId that represents the book on the shelf: the newest cover marked `favorite`, else the newest cover. Null when the book has no covers.
    - `covers_count` integer, required: Every cover of the book, hidden ones included (the dashboard's "N covers").
    - `created_at` string, date-time, required
  - `next_cursor` string, nullable, required: Pass as `cursor` to fetch the next page. `null` when there are no more results.

## Other responses

- `400`: `code` is one of: `invalid_limit`, `invalid_cursor`, `invalid_q`, `invalid_include_hidden`, `invalid_source_type`.
- `401`: Missing/malformed API key, unknown or inactive key, or inactive subscription detected during credit checks. `code`: `unauthorized`.
- `403`: The API key is valid but its owner has no active enterprise subscription. `code`: `forbidden`.
- `500`: Server error. `code` is `fetch_failed` or `internal_error`.

---

[API](https://skmtc.dev/beyourcover/apis/beyourcover-partner-api.md) · [All operations](https://skmtc.dev/beyourcover/apis/beyourcover-partner-api/llms.txt) · [OpenAPI document](https://skmtc.dev/beyourcover/apis/beyourcover-partner-api/revisions/82ad2c7c8ede?raw)