openapi: 3.0.3
info:
  title: Card Source Canada Public API
  description: |
    Public, read-only endpoints for AI agents, LLMs, shopping assistants, and search tools.
    All prices are in Canadian dollars (CAD). Inventory updates in real-time.
  version: 1.0.0
  contact:
    name: Card Source Canada
    email: info@cardsource.ca
    url: https://cardsource.ca/pages/about.php
  termsOfService: https://cardsource.ca/pages/terms.php
servers:
  - url: https://cardsource.ca
paths:
  /api/products.json:
    get:
      summary: Real-time product catalog (JSON-LD)
      description: Returns the full active inventory as a schema.org ItemList with Product and Offer details.
      responses:
        '200':
          description: JSON-LD product catalog
          content:
            application/json:
              schema:
                type: object
  /api/search-suggest.php:
    get:
      summary: Search autocomplete
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
      description: Returns matching cards, players, teams, and sets for a given query string.
      responses:
        '200':
          description: JSON suggestions
  /api/merchant-feed.txt:
    get:
      summary: TSV merchant catalog feed
      description: Tab-separated catalog feed optimized for AI crawlers and merchant systems.
      responses:
        '200':
          description: TSV feed
  /api/merchant-center.xml:
    get:
      summary: Google Merchant Center XML feed
      description: Google Shopping compatible product feed.
      responses:
        '200':
          description: XML feed
  /api/price-guide-data.php:
    get:
      summary: Price guide data
      parameters:
        - name: format
          in: query
          schema:
            type: string
            enum: [json, csv]
      description: Market value estimates for popular cards in CAD.
      responses:
        '200':
          description: JSON or CSV price guide
  /api/chatbot.php:
    post:
      summary: AI assistant chat endpoint
      description: Answers collector questions using live inventory and Gemini. No authentication required.
      responses:
        '200':
          description: JSON chat response
  /ask.php:
    get:
      summary: AI assistant page
      description: Human-facing chatbot interface for card, shipping, and collecting questions.
      responses:
        '200':
          description: HTML page
  /llms.txt:
    get:
      summary: LLM context file
      description: Machine-readable site overview for LLMs, following llmstxt.org convention.
      responses:
        '200':
          description: Plain text
  /.well-known/llms-full.txt:
    get:
      summary: Extended LLM context
      description: Extended business context for AI agents and citation systems.
      responses:
        '200':
          description: Plain text
  /.well-known/ai-plugin.json:
    get:
      summary: AI plugin manifest
      description: ChatGPT/agent plugin manifest describing the store and available APIs.
      responses:
        '200':
          description: JSON manifest
