BeYourCover Templates API

openapi: 3.2.0
info:
  title: BeYourCover Partner Templates API
  version: 1.1.0
  description: 'Enterprise/partner REST API for AI-powered book cover generation: covers from book details or from reference images, variations, edits, replacing a person with a photo, text removal, upscales, audiobook covers, and full print wraps for Amazon KDP with a print-ready PDF. Every endpoint except `GET /api/v1/health` requires a partner API key (`Authorization: Bearer byc_sk_...`). Long-running operations (generation, reference-image generation, variations, edits, replacing a person, text removal, upscales, audiobook covers, print wraps and a wrap''s front-panel re-extension) return `202 Accepted` with a job envelope; poll `GET /api/v1/jobs/{jobId}` or receive a webhook. Re-typesetting a wrap (`POST /api/v1/wraps/{wrapId}/render`) runs no model, so it answers `200` directly. All error responses use a uniform envelope: `{ "error": { "code": string, "message": string } }`.'
servers:
- url: https://beyourcover.com
  description: Production. All paths below are relative to the site origin.
security:
- ApiKeyBearer: []
tags:
- name: Templates
paths:
  /api/v1/templates:
    get:
      tags:
      - Templates
      operationId: listTemplates
      summary: List active cover templates
      description: 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`.
      parameters:
      - name: genre
        in: query
        required: false
        schema:
          type: string
        description: Genre slug (e.g. `science-fiction`) or canonical value (e.g. `Science Fiction`). When given without `subgenre`, returns the union of the templates serving any subgenre under the genre's bucket and the pools its subgenres route to (a Young Adult subgenre routes to a fiction pool).
      - name: subgenre
        in: query
        required: false
        schema:
          type: string
        description: Subgenre value; must be valid for the given `genre`. Requires `genre`. Returns only the templates of the pool that subgenre renders from.
      responses:
        '200':
          description: Template list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateList'
        '400':
          description: '`code` is one of: `missing_genre_for_subgenre`, `invalid_genre`, `invalid_subgenre`.'
          x-error-codes:
          - missing_genre_for_subgenre
          - invalid_genre
          - invalid_subgenre
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          description: Server error. `code` is `internal_error`.
          x-error-codes:
          - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
components:
  responses:
    Forbidden:
      description: 'The API key is valid but its owner has no active enterprise subscription (`forbidden`); or the acting member''s role does not allow the call: a reviewer cannot spend credits or change books (`forbidden_role`), and only the member who created a book may edit it or its covers (`not_book_creator`).'
      x-error-codes:
      - forbidden
      - forbidden_role
      - not_book_creator
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Unauthorized:
      description: 'Missing/malformed API key, unknown or inactive key, or inactive subscription detected during credit checks. `code`: `unauthorized`.'
      x-error-codes:
      - unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  schemas:
    ErrorEnvelope:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Machine-readable error code (snake_case).
            message:
              type: string
              description: Human-readable explanation. For 500s this is always a generic message.
            details:
              type: object
              description: Optional machine-readable recovery information. 402 responses carry { balance, required, billing_url }; unknown-path 404s carry absolute URLs for the OpenAPI spec, documentation, API catalog, authentication guide and health probe.
      description: Uniform error envelope used by every non-2xx JSON response.
    TemplateList:
      type: object
      required:
      - templates
      - total
      properties:
        templates:
          type: array
          items:
            $ref: '#/components/schemas/Template'
        total:
          type: integer
    Template:
      type: object
      required:
      - id
      - name
      - family
      - templateType
      - genreBuckets
      - previewImage
      - variants
      properties:
        id:
          type: string
          description: Template id; usable as `templateId` in POST /api/v1/covers/generate.
        name:
          type: string
        family:
          type:
          - string
          - 'null'
        templateType:
          type:
          - string
          - 'null'
        genreBuckets:
          type:
          - array
          - 'null'
          items:
            type: string
          description: Bucket keys the template serves, typically in `Bucket:subgenre` form.
        previewImage:
          type:
          - string
          - 'null'
          description: Public URL of the template's preview image. `null` when no preview has shipped yet.
        variants:
          type:
          - object
          - 'null'
          additionalProperties:
            type: array
            items:
              type: string
          description: 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:
          type: boolean
          description: '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.'
  securitySchemes:
    ApiKeyBearer:
      type: http
      scheme: bearer
      bearerFormat: byc_sk_{32 hex chars}
      description: 'Partner API key sent as `Authorization: Bearer byc_sk_...`. The key must match `^byc_sk_[0-9a-f]{32}$`. A malformed, unknown, or inactive key yields `401 unauthorized`; a valid key whose owner has no active enterprise subscription yields `403 forbidden`.'