---
title: "List active cover templates"
method: GET
path: "/api/v1/templates"
tags: ["Templates"]
---

# List active cover templates

`GET /api/v1/templates`

## Request

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

Lists the active cover templates, sorted by name, optionally filtered by genre and subgenre. The list comes from the same template catalog that `POST /api/v1/covers/generate` checks `templateId` against, so every listed `id` can be pinned. Each template carries its `previewImage` URL and its `variants`. With `subgenre`, the list is the pool that subgenre renders from, and each template also carries `subgenreMatch` (always `true`). `subgenre` requires `genre`.

## Query parameters

- `genre` string
- `subgenre` string

## Response `200`

Template list.

- TemplateList
  - `templates` Template[], required
    - `id` string, required: Template id; usable as `templateId` in POST /api/v1/covers/generate.
    - `name` string, required
    - `family` string, nullable, required
    - `templateType` string, nullable, required
    - `genreBuckets` string[], nullable, required: Bucket keys the template serves, typically in `Bucket:subgenre` form.
    - `previewImage` string, nullable, required: Public URL of the template's preview image. `null` when no preview has shipped yet.
    - `variants` object, nullable, required: Style axes (e.g. `fontStyle`, `titleColor`), each mapped to the options the engine picks one from when it renders the template. A generate request cannot choose an option.
    - `subgenreMatch` boolean: Only present when the request included a `subgenre` query parameter. Always `true`: a subgenre list holds only that subgenre's pool. Kept for older clients.
  - `total` integer, required

## Other responses

- `400`: `code` is one of: `missing_genre_for_subgenre`, `invalid_genre`, `invalid_subgenre`.
- `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 `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)