sketchxflow-com Logos API

openapi: 3.2.0
info:
  title: SketchXFlow Logos API
  version: 0.1.0
tags:
- name: Logos
paths:
  /api/logos:
    get:
      summary: List Logos
      description: 'List the current user''s logo kits — newest first. Only includes

        the lightweight overview fields; the full asset URL set is fetched

        via GET /api/logos/{kit_id}.'
      operationId: list_logos_api_logos_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Logos
  /api/logos/{kit_id}:
    get:
      summary: Get Logo
      description: Full kit document including every asset URL.
      operationId: get_logo_api_logos__kit_id__get
      parameters:
      - name: kit_id
        in: path
        required: true
        schema:
          type: string
          title: Kit Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Logos
    delete:
      summary: Delete Logo
      operationId: delete_logo_api_logos__kit_id__delete
      parameters:
      - name: kit_id
        in: path
        required: true
        schema:
          type: string
          title: Kit Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Logos
  /api/logos/{kit_id}/asset/{key}:
    get:
      summary: Proxy Kit Asset
      description: 'Same-origin proxy for the kit''s stored assets. GCS returns no

        Access-Control-Allow-Origin, so the browser refuses cross-origin

        fetch() calls used by the SVG preview component. Routing through

        here makes the asset same-origin and unblocks the inline-SVG render

        (lockups + wordmark).'
      operationId: proxy_kit_asset_api_logos__kit_id__asset__key__get
      parameters:
      - name: kit_id
        in: path
        required: true
        schema:
          type: string
          title: Kit Id
      - name: key
        in: path
        required: true
        schema:
          type: string
          title: Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Logos
  /api/logos/{kit_id}/recolor:
    post:
      summary: Recolor Logo
      description: 'Recolor an existing logo kit. Two modes:


        `instant` (default) — hue-shifts the existing symbol so the

        dominant color matches the new primary, re-derives every PNG

        variant, and recomposes the wordmark + lockup SVGs with the

        new ink. The concept stays identical; only colors change.

        Typical latency: 2-5s, no LLM cost.


        `regenerate` — re-runs the AI symbol generator with the new

        palette locked into the brief. May produce a different shape

        because Gemini is non-deterministic. Latency: 30-90s. Use

        when the user wants a fresh take, not just a recolor.


        Both modes overwrite the same kit_id''s assets in GCS so existing

        consumers (preview, brand book PDF) see the new colors on next

        fetch — no new IDs to track.'
      operationId: recolor_logo_api_logos__kit_id__recolor_post
      parameters:
      - name: kit_id
        in: path
        required: true
        schema:
          type: string
          title: Kit Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/_RecolorRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Logos
  /api/logos/{kit_id}/revert:
    post:
      summary: Revert Logo
      description: 'Atomically swap the kit''s current and previous versions.


        Both versions already exist on GCS at distinct versioned paths

        (logos/{kit_id}/v{N}/...). The swap is a pure Mongo doc rewrite —

        no GCS rewriting, no LLM call, no re-deriving anything. The

        swap is reversible: calling revert again puts you back where

        you started, then again to the new state, ad infinitum.


        Returns 400 when there''s no previous version to revert to.'
      operationId: revert_logo_api_logos__kit_id__revert_post
      parameters:
      - name: kit_id
        in: path
        required: true
        schema:
          type: string
          title: Kit Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Logos
  /api/logos/{kit_id}/pack/{kind}:
    get:
      summary: Download Kit Pack
      description: 'Download a curated ZIP of the kit''s assets for a delivery context.


        `kind` is one of:

        mobile — iOS + Android launcher icons (App Store rejects

        transparent icons, so iOS variants are opaque white)

        website — favicon set, Apple Touch, PWA icons, OG + Twitter

        social-share canvases, ready-to-paste snippet

        brand — high-res symbol PNGs + monochrome variants + SVGs

        (the designer''s working bundle)

        print — 4096 px PNGs + native SVGs for print compositing'
      operationId: download_kit_pack_api_logos__kit_id__pack__kind__get
      parameters:
      - name: kit_id
        in: path
        required: true
        schema:
          type: string
          title: Kit Id
      - name: kind
        in: path
        required: true
        schema:
          type: string
          title: Kind
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Logos
  /api/logos/{kit_id}/render:
    get:
      summary: Render Kit Asset
      description: 'Render a single kit asset at custom dimensions with optional

        background. The "Custom size" tool in the UI lives on this route.


        Query params:

        asset — symbol | mono_black | mono_white | symbol_dark

        (defaults to symbol)

        w, h — pixel dimensions. `h=0` means "same as width" (square).

        Both are clamped to [16, 4096].

        bg — `transparent` (default), `light`, `dark`, `brand`,

        or a literal `#RRGGBB` hex.


        Returns the rendered PNG inline so the browser can pipe it straight

        to or a download. The cap prevents pathological 32k×32k

        requests from running the worker out of memory.'
      operationId: render_kit_asset_api_logos__kit_id__render_get
      parameters:
      - name: kit_id
        in: path
        required: true
        schema:
          type: string
          title: Kit Id
      - name: asset
        in: query
        required: false
        schema:
          type: string
          default: symbol
          title: Asset
      - name: w
        in: query
        required: false
        schema:
          type: integer
          default: 512
          title: W
      - name: h
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: H
      - name: bg
        in: query
        required: false
        schema:
          type: string
          default: transparent
          title: Bg
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Logos
  /api/logos/{kit_id}/explain:
    post:
      summary: Explain Logo
      description: 'Generate (and cache) a human explanation of WHY this logo suits the

        brand — a one-line concept + a short rationale. Older kits were saved

        without a rationale; this backfills it on demand so the details page

        always has a meaning to show.'
      operationId: explain_logo_api_logos__kit_id__explain_post
      parameters:
      - name: kit_id
        in: path
        required: true
        schema:
          type: string
          title: Kit Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Logos
  /api/logos/{kit_id}/brand-book.pdf:
    get:
      summary: Download Brand Book
      description: 'Render a polished multi-page PDF brand book for this kit. Pages:

        cover, concept, symbol variants, lockup, palette, typography,

        favicons, usage rules. Inline-served so the browser previews it.'
      operationId: download_brand_book_api_logos__kit_id__brand_book_pdf_get
      parameters:
      - name: kit_id
        in: path
        required: true
        schema:
          type: string
          title: Kit Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Logos
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    _RecolorRequest:
      properties:
        palette:
          items:
            type: string
          type: array
          maxItems: 8
          minItems: 1
          title: Palette
        mode:
          type: string
          pattern: ^(instant|regenerate)$
          title: Mode
          default: instant
      type: object
      required:
      - palette
      title: _RecolorRequest