openapi: 3.1.0
info:
  title: Brand Peel API
  version: 1.0.0
  description: Public API and agent integration endpoints for Brand Peel — the local-first desktop AI brand strategist and design token compiler.
  termsOfService: "https://brandpeel.app/legal/imprint"
  contact:
    name: Brand Peel Support
    url: "https://brandpeel.app/contact"
    email: "support@brandpeel.app"
  license:
    name: MIT
    url: "https://opensource.org/licenses/MIT"
x-api-deprecation-policy:
  versioningScheme: URL path (/api/v1/)
  deprecationNotice: "Deprecated endpoints will return a Deprecation: true header and a Sunset header with the removal date at least 90 days in advance."
  currentVersion: 1.0.0
  sunsetPolicy: "https://brandpeel.app/developers#api-versioning"
servers:
  - url: "https://brandpeel.app"
    description: Brand Peel Production Server
paths:
  /api/v1/health:
    get:
      operationId: getHealthStatus
      summary: Check API and agent service health
      description: "Returns operational status, version, and links to machine-readable agent discovery documents."
      responses:
        200:
          description: Service is operational
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/v1/release/latest:
    get:
      operationId: getLatestReleaseDownload
      summary: Retrieve latest desktop release downloads and checksums
      description: "Provides download URLs for Windows (setup/portable x64), macOS (universal/arm64/x64 DMG), and Linux (AppImage/portable)."
      parameters:
        - name: platform
          in: query
          required: false
          description: Filter by operating system platform.
          schema:
            type: string
            enum:
              - windows
              - macos
              - linux
        - name: channel
          in: query
          required: false
          description: Release channel to fetch.
          schema:
            type: string
            enum:
              - stable
              - alpha
              - beta
            default: alpha
      responses:
        200:
          description: Release downloads payload
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReleaseResponse"
        400:
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/v1/tools:
    get:
      operationId: listBrandTools
      summary: List or search free branding and design tools
      description: "Returns the catalog of free utilities for color generation, typography, contrast calculation, and token export."
      parameters:
        - name: category
          in: query
          required: false
          description: Filter tools by category name.
          schema:
            type: string
        - name: q
          in: query
          required: false
          description: Search query for keywords or tool names.
          schema:
            type: string
      responses:
        200:
          description: List of matching tools and categories
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ToolListResponse"
  /api/v1/tools/{slug}:
    get:
      operationId: getBrandToolBySlug
      summary: Retrieve single brand tool specification
      description: "Returns metadata, outcome description, URL, and keywords for an individual tool."
      parameters:
        - name: slug
          in: path
          required: true
          description: The unique slug identifier of the tool.
          schema:
            type: string
      responses:
        200:
          description: Tool details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ToolDetail"
        404:
          description: Tool not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/v1/brand-guide/schema:
    get:
      operationId: getBrandGuideSchema
      summary: Retrieve Brand Peel export JSON Schema
      description: "Returns the standard schema for brand books, design tokens, color models (OKLCH/HSL/Hex), and Tailwind v4 configurations."
      responses:
        200:
          description: JSON Schema document
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BrandGuideSchemaResponse"
  /api/v1/agent-info:
    get:
      operationId: getAgentCapabilities
      summary: Get agent integration capabilities and when-to-use guidance
      description: Returns machine-readable information on when and how AI agents should utilize Brand Peel.
      responses:
        200:
          description: Agent capabilities and guidance
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentInfoResponse"
  /api/v1/cli/manifest:
    get:
      operationId: getCliManifest
      summary: Get Brand Peel CLI tool manifest
      description: Provides command options and package specifications for scripting brand token operations.
      responses:
        200:
          description: CLI tool manifest
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CliManifestResponse"
components:
  schemas:
    ErrorResponse:
      type: object
      required:
        - error
        - statusCode
        - message
      properties:
        error:
          type: string
          example: NOT_FOUND
        statusCode:
          type: integer
          example: 404
        message:
          type: string
          example: The requested resource was not found.
        resolutionHints:
          type: array
          items:
            type: string
          example:
            - Check URL for typos
            - "Inspect https://brandpeel.app/openapi.json"
        documentationUrl:
          type: string
          example: "https://brandpeel.app/developers"
    HealthResponse:
      type: object
      required:
        - status
        - service
        - version
        - timestamp
      properties:
        status:
          type: string
          example: healthy
        service:
          type: string
          example: Brand Peel Public API
        version:
          type: string
          example: 1.0.0
        timestamp:
          type: string
          format: date-time
        agentReadiness:
          type: object
          properties:
            openApiSpec:
              type: string
              format: uri
              example: "https://brandpeel.app/openapi.json"
            llmsSummary:
              type: string
              format: uri
              example: "https://brandpeel.app/llms.txt"
            llmsFull:
              type: string
              format: uri
              example: "https://brandpeel.app/llms-full.txt"
            agentInstructions:
              type: string
              format: uri
              example: "https://brandpeel.app/agent-instructions.md"
            developerPortal:
              type: string
              format: uri
              example: "https://brandpeel.app/developers"
            acceptMarkdownCompliant:
              type: boolean
              example: true
    ReleaseResponse:
      type: object
      required:
        - version
        - channel
      properties:
        version:
          type: string
          example: 0.1.0-alpha
        channel:
          type: string
          enum:
            - stable
            - alpha
            - beta
          example: alpha
        platforms:
          type: object
          properties:
            windows:
              type: object
              properties:
                x64:
                  type: object
                  properties:
                    setup:
                      type: string
                      format: uri
                    portable:
                      type: string
                      format: uri
            macos:
              type: object
              properties:
                universal:
                  type: object
                  properties:
                    dmg:
                      type: string
                      format: uri
                arm64:
                  type: object
                  properties:
                    dmg:
                      type: string
                      format: uri
                x64:
                  type: object
                  properties:
                    dmg:
                      type: string
                      format: uri
            linux:
              type: object
              properties:
                x64:
                  type: object
                  properties:
                    appimage:
                      type: string
                      format: uri
                    portable:
                      type: string
                      format: uri
                arm64:
                  type: object
                  properties:
                    portable:
                      type: string
                      format: uri
        documentation:
          type: string
          format: uri
        downloadsPage:
          type: string
          format: uri
    ToolDetail:
      type: object
      required:
        - id
        - name
        - summary
        - category
        - outcome
        - url
      properties:
        id:
          type: string
        name:
          type: string
        summary:
          type: string
        category:
          type: string
        outcome:
          type: string
        url:
          type: string
        path:
          type: string
        keywords:
          type: array
          items:
            type: string
    ToolListResponse:
      type: object
      required:
        - total
        - tools
        - categories
      properties:
        total:
          type: integer
        tools:
          type: array
          items:
            $ref: "#/components/schemas/ToolDetail"
        categories:
          type: array
          items:
            type: object
            properties:
              slug:
                type: string
              name:
                type: string
              description:
                type: string
              url:
                type: string
    AgentInfoResponse:
      type: object
      required:
        - name
        - description
        - homepage
        - whenToUse
        - functions
      properties:
        name:
          type: string
          example: Brand Peel
        description:
          type: string
        homepage:
          type: string
          format: uri
        developerPortal:
          type: string
          format: uri
        openApiSpec:
          type: string
          format: uri
        whenToUse:
          type: array
          items:
            type: string
        whenNotToUse:
          type: array
          items:
            type: string
        functions:
          type: array
          items:
            type: object
            required:
              - name
              - description
              - parameters
            properties:
              name:
                type: string
                description: Unique function name matching an OpenAPI operationId.
              description:
                type: string
                description: Human-readable description of what the function does.
              parameters:
                type: object
                description: JSON Schema object describing accepted parameters.
                properties:
                  type:
                    type: string
                    enum:
                      - object
                  properties:
                    type: object
    CliManifestResponse:
      type: object
      required:
        - package
        - version
        - commands
      properties:
        package:
          type: string
          example: brandpeel
        npmUrl:
          type: string
          format: uri
          example: "https://www.npmjs.com/package/brandpeel"
        install:
          type: object
          properties:
            global:
              type: string
              example: npm install -g brandpeel
            npx:
              type: string
              example: npx brandpeel
            pnpm:
              type: string
              example: pnpm dlx brandpeel
        version:
          type: string
          example: 0.1.0
        description:
          type: string
        commands:
          type: array
          items:
            type: object
            required:
              - command
              - summary
            properties:
              command:
                type: string
                description: CLI command syntax.
              summary:
                type: string
                description: What the command does.
              options:
                type: array
                items:
                  type: object
                  required:
                    - flag
                    - description
                  properties:
                    flag:
                      type: string
                    description:
                      type: string
    BrandGuideSchemaResponse:
      type: object
      required:
        - $schema
        - $id
        - title
        - description
        - type
        - required
        - properties
      properties:
        $schema:
          type: string
          example: "https://json-schema.org/draft/2020-12/schema"
        $id:
          type: string
          example: "https://brandpeel.app/api/v1/brand-guide/schema"
        title:
          type: string
          example: BrandPeelBrandPackage
        description:
          type: string
        type:
          type: string
          example: object
        required:
          type: array
          items:
            type: string
        properties:
          type: object
          properties:
            version:
              type: object
            brand:
              type: object
            strategy:
              type: object
            tokens:
              type: object
            exports:
              type: object
