---
title: "List a book's motif candidates"
method: GET
path: "/api/v1/books/{bookId}/motifs"
tags: ["Books"]
---

# List a book's motif candidates

`GET /api/v1/books/{bookId}/motifs`

## Request

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

Lists the book's motif candidates: the story objects, symbols and places the V2 engine extracted from its summary, plus any added in the app (user-added first). Pass one `id` as `motif_id` on POST /api/v1/covers/generate. A new book has none until its first template generation. Free.

## Path parameters

- `bookId` string, uuid, required

## Response `200`

The book's motifs.

- BookMotifList
  - `bookId` string, uuid, required
  - `motifs` object[], required
    - `id` string, required: Pass as `motif_id` on POST /api/v1/covers/generate.
    - `label` string, required
    - `description` string, required
    - `type` string, required: A motif kind (`object`, `symbol`, `place`, `structure`, `interior`) or a composition role.
    - `user_added` boolean, required: True for a motif the author added in the app.
  - `allowed_types` string[], required: The motif types the book's template pool renders.

## Other responses

- `400`: `code`: `missing_book_id`.
- `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`.
- `404`: Book not found or not owned by this API key's account. `code`: `book_not_found`.
- `500`: Server error. `code`: `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)