BeYourCover Account API

openapi: 3.2.0
info:
  title: BeYourCover Partner Account 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: Account
  description: Subscription credits and API capability discovery.
paths:
  /api/v1/capabilities:
    get:
      tags:
      - Account
      operationId: getCapabilities
      summary: Discover genre coverage and operation costs
      description: 'Machine-readable capability report: every genre/subgenre with honest generation-coverage flags (derived from the same routing modules the generate endpoint gates on), the static per-operation credit costs, and request limits. Static per deploy.'
      responses:
        '200':
          description: Capability report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Capabilities'
        '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'
  /api/v1/credits:
    get:
      tags:
      - Account
      operationId: getCredits
      summary: Get credit balance and plan
      description: Current credit balances (monthly + overage), plan tier, and concurrency limit for the authenticated subscription. `marketing_kits` lists the books whose marketing kit is open this period and the included renders (print wrap, audiobook cover, text-free cover) each still has.
      responses:
        '200':
          description: Credit and plan summary.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditSummary'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: 'The subscription row disappeared between auth and lookup. `code`: `subscription_not_found`.'
          x-error-codes:
          - subscription_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: Server error. `code` is `internal_error`.
          x-error-codes:
          - internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
components:
  schemas:
    Capabilities:
      type: object
      required:
      - api_version
      - generation_engine
      - genres
      - operations
      - limits
      - coverage_note
      properties:
        api_version:
          type: string
        generation_engine:
          type: string
        genres:
          type: array
          items:
            $ref: '#/components/schemas/CapabilityGenre'
          description: Every canonical genre with honest per-subgenre generation coverage, derived from the same routing modules the generate endpoint gates on.
        operations:
          type: object
          description: Static per-operation credit costs, keyed by job operation.
          additionalProperties:
            type: object
            required:
            - credits_per_image
            - description
            properties:
              credits_per_image:
                type:
                - integer
                - 'null'
                description: 'null for `wrap`, which is priced per design: see `credits_by_style`. For `replace_person` the price is per call: one call makes up to two covers.'
              credits_by_style:
                type: object
                additionalProperties:
                  type: integer
                description: '`wrap` only: credits per back-cover design style.'
              included_with_marketing_kit:
                type: boolean
                description: 'true for `wrap`, `audiobook_cover` and `remove_text`: the book''s first one costs 0 credits when its marketing kit was opened in the app this billing period.'
              description:
                type: string
        limits:
          type: object
          properties:
            max_covers_per_generate:
              type: integer
        coverage_note:
          type: string
    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.
    CapabilityGenre:
      type: object
      required:
      - genre
      - slug
      - supported
      - subgenre_auto_detected
      - subgenres
      properties:
        genre:
          type: string
          description: Canonical genre value.
        slug:
          type: string
          description: API genre slug (accepted by POST /api/v1/books).
        supported:
          type: boolean
          description: Whether cover generation works for this genre at all — true for every current genre. An unsupported genre would return `422 unsupported_genre` from generate.
        subgenre_auto_detected:
          type: boolean
          description: When true, POST /api/v1/books auto-detects a subgenre from the book details if the caller omits one.
        subgenres:
          type: array
          items:
            type: object
            required:
            - value
            - label
            - supported
            properties:
              value:
                type: string
              label:
                type: string
              supported:
                type: boolean
    CreditSummary:
      type: object
      required:
      - tier
      - credits_remaining
      - credits_monthly
      - overage_credits
      - total_available
      - concurrent_limit
      - is_active
      - billing_url
      - marketing_kits
      properties:
        tier:
          type: string
          description: Plan tier (e.g. `starter`, `growth`, `scale`).
        credits_remaining:
          type: integer
          description: Unused monthly credits.
        credits_monthly:
          type: integer
          description: Monthly allowance at renewal.
        overage_credits:
          type: integer
          description: Purchased overage credits.
        total_available:
          type: integer
          description: credits_remaining + overage_credits.
        concurrent_limit:
          type: integer
          description: Max queued/processing jobs at once.
        is_active:
          type: boolean
        billing_url:
          type: string
          format: uri
          description: Where a human can manage the plan / top up.
        marketing_kits:
          $ref: '#/components/schemas/MarketingKitMeter'
    MarketingKitMeter:
      type: object
      required:
      - period_key
      - kits_left
      - kits_total
      - kits_used
      - books
      description: 'The marketing-kit book meter. Opening a book''s marketing kit in the app spends one kit of the plan''s allowance for the billing period and includes one print wrap, one audiobook cover and one text-free cover for that book: the first `POST /api/v1/wraps`, `audiobook-cover` and `remove-text` on it cost 0 credits. Display only: the render decides the price when it runs.'
      properties:
        period_key:
          type: string
          description: The billing period, `YYYY-MM`.
        kits_left:
          type:
          - integer
          - 'null'
          description: Marketing kits the plan can still open this period. Null when the plan has no kit allowance.
        kits_total:
          type:
          - integer
          - 'null'
        kits_used:
          type:
          - integer
          - 'null'
          description: 'Kits of the plan''s allowance spent this period (`books_used`, the number the Enterprise dashboard shows). It can be lower than the length of `books`: a book opened earlier under the same `period_key` and a paid extra book are in `books` but spend no kit.'
        books:
          type:
          - array
          - 'null'
          description: 'Every book with a marketing kit under this `period_key`, newest first, including paid extra books and books opened earlier in the same key. Null when the meter could not be read: assume no included renders.'
          items:
            type: object
            required:
            - bookId
            - title
            - included_formats_left
            properties:
              bookId:
                type: string
                format: uuid
              title:
                type:
                - string
                - 'null'
              included_formats_left:
                type: array
                items:
                  type: string
                  enum:
                  - print_wrap
                  - audiobook
                  - text_free
                description: Included renders this book still has. Empty when all are used or the kit expired.
  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'
  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`.'