openapi: 3.0.3
info:
  title: PureGuard Apparel — Knowledge Catalog & Discovery API
  version: 1.0.0
  description: |
    Discoverable API for the PureGuard Apparel Knowledge Catalog.

    Optimized for both traditional search engines (via the JSON-LD + llms.txt manifests)
    and AI agents (LLMs, enterprise copilots, autonomous agents). Every endpoint is
    public, idempotent, and rate-limited per IP.

    Endpoints:
      - GET /catalog/api/assets            : List all knowledge assets (paginated).
      - GET /catalog/api/assets/{id}       : Get one knowledge asset with full metadata.
      - GET /catalog/api/search             : Hybrid search across title, summary, tags, keywords.
      - GET /catalog/api/categories         : Aggregate counts by asset type.
      - GET /catalog/api/graph              : Typed knowledge graph (nodes + edges).
      - GET /catalog/api/scores            : AI optimisation scores per asset.
      - GET /catalog/llms.txt               : Human-and-AI-readable directory.
      - GET /catalog/llms-full.txt          : Full content of the catalog.
servers:
  - url: https://pureguardapparel.com
paths:
  /catalog/api/assets:
    get:
      summary: List knowledge assets
      description: Returns all knowledge assets with pagination, filtering and sorting.
      parameters:
        - name: type
          in: query
          description: Filter by asset type (garment, branding-technique, page, faq, policy, sop, form, lead-magnet, spec, article, image, video, download, service).
          schema: { type: string }
        - name: tag
          in: query
          schema: { type: string }
        - name: min_geo
          in: query
          description: Minimum GEO score.
          schema: { type: number, format: float, minimum: 0, maximum: 1 }
        - name: limit
          in: query
          schema: { type: integer, default: 50, maximum: 200 }
        - name: offset
          in: query
          schema: { type: integer, default: 0 }
      responses:
        '200':
          description: Array of knowledge assets
          content:
            application/json:
              schema:
                type: object
                properties:
                  total: { type: integer }
                  items:
                    type: array
                    items: { $ref: '#/components/schemas/KnowledgeAsset' }
  /catalog/api/assets/{id}:
    get:
      summary: Get one knowledge asset
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Single knowledge asset
          content:
            application/json:
              schema: { $ref: '#/components/schemas/KnowledgeAsset' }
        '404':
          description: Not found
  /catalog/api/search:
    get:
      summary: Hybrid keyword + tag search over catalog
      parameters:
        - name: q
          in: query
          required: true
          schema: { type: string }
        - name: type
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Array of assets with relevance score
  /catalog/api/categories:
    get:
      summary: Asset counts grouped by type
      responses:
        '200':
          description: Object of type -> count
  /catalog/api/graph:
    get:
      summary: Typed knowledge graph
      responses:
        '200':
          description: Nodes + edges
  /catalog/api/scores:
    get:
      summary: AI optimisation scores per asset
      responses:
        '200':
          description: Object of asset scores
  /catalog/llms.txt:
    get:
      summary: Human-and-AI-readable directory of the site
      responses:
        '200':
          description: Plain text directory
  /catalog/llms-full.txt:
    get:
      summary: Full body content of every public page
      responses:
        '200':
          description: Plain text corpus
components:
  schemas:
    KnowledgeAsset:
      type: object
      properties:
        id: { type: string }
        type: { type: string }
        title: { type: string }
        summary: { type: string }
        owner: { type: string }
        department: { type: string }
        tags: { type: array, items: { type: string } }
        keywords: { type: array, items: { type: string } }
        entities: { type: array, items: { type: string } }
        business_concepts: { type: array, items: { type: string } }
        confidence_score: { type: number }
        trust_score: { type: number }
        ai_readiness_score: { type: number }
        seo_score: { type: number }
        geo_score: { type: number }
        last_reviewed: { type: string, format: date }
        review_frequency_days: { type: integer }
        source_location: { type: string }
        permissions: { type: string, enum: [public, authenticated, internal, restricted] }
        version: { type: string }
        related_assets: { type: array, items: { type: string } }