BeYourCover Service API

openapi: 3.2.0
info:
  title: BeYourCover Partner Service 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: Service
  description: Unauthenticated service discovery and health. Linked from the RFC 9727 API catalog at `/.well-known/api-catalog`.
paths:
  /api/v1/health:
    get:
      tags:
      - Service
      operationId: getHealth
      summary: Liveness probe
      description: Public liveness check — the only endpoint that needs no API key. Reports that the API is serving requests; it does not check downstream dependencies (database, payment, or image providers), so a `200` here does not promise that a generation will succeed. Per-operation availability is reported by `GET /api/v1/capabilities`. This is the `status` target of the RFC 9727 API catalog at `/.well-known/api-catalog`. Responses are not cached.
      security: []
      responses:
        '200':
          description: API is serving requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Health'
components:
  schemas:
    Health:
      type: object
      required:
      - status
      - service
      - version
      properties:
        status:
          type: string
          enum:
          - ok
          description: Always `ok` when the API responds. Unreachability is signalled by the transport (connection failure or a 5xx), not by this field.
        service:
          type: string
          description: Service name, matching `info.title` in the OpenAPI spec.
        version:
          type: string
          description: API contract version, matching `info.version` in the OpenAPI spec.
  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`.'