{
  "openapi": "3.1.0",
  "info": {
    "title": "AI Brand Trust Registry API",
    "description": "Public API for accessing AI-generated brand profiles from the AI Brand Trust Registry. Returns structured data about how AI models describe and categorize brands, including shopping intelligence.",
    "version": "1.5.0",
    "contact": {
      "name": "Optimly",
      "url": "https://optimly.ai",
      "email": "founders@optimly.ai"
    }
  },
  "servers": [
    {
      "url": "https://ghhojtvpyevqgqgpqokj.supabase.co/functions/v1",
      "description": "Production"
    }
  ],
  "paths": {
    "/brand-api": {
      "get": {
        "operationId": "listBrands",
        "summary": "List brands in the directory",
        "description": "Returns a paginated list of brands with optional category filtering.",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "description": "Filter by category (case-insensitive partial match)",
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Number of results (max 200, default 50)",
            "schema": { "type": "integer", "default": 50, "maximum": 200 }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Pagination offset",
            "schema": { "type": "integer", "default": 0 }
          }
        ],
        "responses": {
          "200": {
            "description": "List of brands",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": { "type": "integer" },
                    "offset": { "type": "integer" },
                    "limit": { "type": "integer" },
                    "category": { "type": "string", "nullable": true },
                    "brands": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/BrandSummary" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/brand-api?slug={slug}": {
      "get": {
        "operationId": "getBrandProfile",
        "summary": "Get a single brand profile",
        "description": "Returns the full AI-generated profile for a specific brand, including AI description consensus, discoverability stats, entity context, and timeliness signals.",
        "parameters": [
          {
            "name": "slug",
            "in": "query",
            "required": true,
            "description": "Brand slug (e.g. 'slack', 'notion', 'retool')",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Brand profile",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/BrandProfile" }
              }
            }
          },
          "404": {
            "description": "Brand not found"
          }
        }
      }
    },
    "/brand-api?action=subcategories&category={category}": {
      "get": {
        "operationId": "getSubcategories",
        "summary": "Browse subcategories within a category",
        "description": "Returns distinct subcategories and their brands within a given canonical category slug. Useful for building subcategory navigation and taxonomy browsing.",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": true,
            "description": "Canonical category slug (e.g. 'fintech-financial-services', 'developer-tools')",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Subcategories with brands",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "category": { "type": "string" },
                    "subcategory_count": { "type": "integer" },
                    "total_brands": { "type": "integer" },
                    "subcategories": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "subcategory": { "type": "string" },
                          "brand_count": { "type": "integer" },
                          "brands": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "slug": { "type": "string" },
                                "name": { "type": "string" },
                                "bai_tier": { "type": "string" },
                                "archetype": { "type": "string" }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/brand-api?action=buyer_simulation": {
      "get": {
        "operationId": "buyerSimulation",
        "summary": "Simulate a buyer query to find relevant brands",
        "description": "Returns brands in a category ranked by a combination of BAI score and subcategory text relevance to the buyer's query. Niche-relevant brands with lower BAI scores get boosted when their subcategory matches the query.",
        "parameters": [
          {
            "name": "category_slug",
            "in": "query",
            "required": true,
            "description": "Canonical category slug (e.g. 'developer-tools', 'fintech-financial-services')",
            "schema": { "type": "string" }
          },
          {
            "name": "query",
            "in": "query",
            "description": "Buyer's natural language query (e.g. 'I need help fixing my broken Lovable app')",
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Number of results (max 25, default 10)",
            "schema": { "type": "integer", "default": 10, "maximum": 25 }
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked brands with relevance scores",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "category_slug": { "type": "string" },
                    "query": { "type": "string", "nullable": true },
                    "result_count": { "type": "integer" },
                    "total_in_category": { "type": "integer" },
                    "brands": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "slug": { "type": "string" },
                          "name": { "type": "string" },
                          "bai_tier": { "type": "string" },
                          "archetype": { "type": "string" },
                          "category": { "type": "string", "nullable": true },
                          "subcategory": { "type": "string", "nullable": true },
                          "relevance_score": { "type": "integer", "description": "Combined BAI + subcategory match score" },
                          "match_reason": { "type": "string", "description": "Why this brand ranked here: 'Subcategory match: X' or 'Category match'" },
                          "vitals": { "type": "object", "nullable": true },
                          "claims": { "type": "array", "items": { "type": "object" } },
                          "profile_url": { "type": "string", "format": "uri" }
                        }
                      }
                    },
                    "brands_ai_would_miss": {
                      "type": "array",
                      "description": "Low-BAI brands that match the query subcategory but would be invisible to AI",
                      "items": { "type": "object" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/brand-api?action=find_by_intent": {
      "get": {
        "operationId": "findByIntent",
        "summary": "Find brands by buyer intent query",
        "description": "Semantic relevance search across all brands. Scores brands by weighted word overlap against subcategory, claims, description, and vitals fields. Returns brands ranked by relevance to the buyer's natural language query, regardless of BAI score.",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "description": "Buyer's natural language query (e.g. 'fix my broken Lovable app')",
            "schema": { "type": "string" }
          },
          {
            "name": "category",
            "in": "query",
            "description": "Optional canonical category slug to narrow search",
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Number of results (max 25, default 5)",
            "schema": { "type": "integer", "default": 5, "maximum": 25 }
          }
        ],
        "responses": {
          "200": {
            "description": "Brands ranked by relevance to the query",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "query": { "type": "string" },
                    "category": { "type": "string", "nullable": true },
                    "results_count": { "type": "integer" },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "slug": { "type": "string" },
                          "name": { "type": "string" },
                          "bai_tier": { "type": "string" },
                          "archetype": { "type": "string" },
                          "category": { "type": "string", "nullable": true },
                          "subcategory": { "type": "string", "nullable": true },
                          "relevance_score": { "type": "integer", "description": "Weighted word overlap score" },
                          "match_signals": {
                            "type": "array",
                            "description": "Explains WHY this brand matched the query",
                            "items": {
                              "type": "object",
                              "properties": {
                                "field": { "type": "string", "description": "Which data field matched (e.g. 'subcategory', 'product_claim', 'description')" },
                                "matched_words": { "type": "array", "items": { "type": "string" } },
                                "claim": { "type": "string", "nullable": true, "description": "The claim name if field is a claim type" }
                              }
                            }
                          },
                          "key_claims": {
                            "type": "array",
                            "description": "Top 5 brand claims prioritized by type (cta > product > pricing > differentiator > market)",
                            "items": {
                              "type": "object",
                              "properties": {
                                "type": { "type": "string" },
                                "name": { "type": "string" },
                                "value": { "type": "string", "nullable": true }
                              }
                            }
                          },
                          "description": { "type": "string" },
                          "profile_url": { "type": "string", "format": "uri" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BrandSummary": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "bai_score": { "type": "integer", "description": "AI Visibility Score (1-100)" },
          "bai_tier": { "type": "string", "enum": ["Strong", "Moderate", "Weak"], "description": "Tier derived from BAI score" },
          "archetype": { "type": "string", "enum": ["Phantom", "Misread", "Challenger", "Incumbent", "Under Scrutiny"] },
          "category": { "type": "string", "nullable": true },
          "subcategory": { "type": "string", "nullable": true, "description": "Subcategory within the main category (e.g. 'Digital Banking' within 'Fintech')" },
          "url": { "type": "string", "format": "uri" },
          "api_url": { "type": "string", "format": "uri" },
          "generated_at": { "type": "string", "format": "date-time" }
        }
      },
      "BrandProfile": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "website_url": { "type": "string", "format": "uri", "nullable": true, "description": "The brand's website URL" },
          "identity": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "category": { "type": "string" },
              "subcategory": { "type": "string" },
              "founded": { "type": "string" },
              "headquarters": { "type": "string" },
              "website": { "type": "string" },
              "description": { "type": "string" }
            }
          },
          "bai_score": { "type": "integer" },
          "archetype": { "type": "string" },
          "category": { "type": "string", "nullable": true },
          "subcategory": { "type": "string", "nullable": true },
          "canonical_category": { "type": "string", "nullable": true, "description": "Normalized category slug from the taxonomy" },
          "sentiment": {
            "type": "object",
            "nullable": true,
            "properties": {
              "score": { "type": "integer" },
              "label": { "type": "string" },
              "dominant_themes": { "type": "array", "items": { "type": "string" } },
              "summary": { "type": "string" }
            }
          },
          "ai_readiness": { "type": "object", "nullable": true },
          "ai_descriptions": { "$ref": "#/components/schemas/AIDescriptions" },
          "discoverability": { "$ref": "#/components/schemas/Discoverability" },
          "entity_context": { "$ref": "#/components/schemas/EntityContext" },
          "competitors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": { "type": "string" },
                "slug": { "type": "string" }
              }
            }
          },
          "vitals": { "$ref": "#/components/schemas/Vitals" },
          "verified": { "type": "boolean" },
          "claimed_by_brand": { "type": "boolean" },
          "llms_txt_found": { "type": "boolean" },
          "generated_at": { "type": "string", "format": "date-time" },
          "timeliness": { "$ref": "#/components/schemas/Timeliness" },
          "content_strategy": { "$ref": "#/components/schemas/ContentStrategy" },
          "category_pricing": {
            "type": "array",
            "description": "Product category-level pricing breakdown from Shopify store data.",
            "items": { "$ref": "#/components/schemas/CategoryPricing" }
          },
          "claims": {
            "type": "array",
            "description": "Structured brand claims extracted from profile narrative (certifications, materials, sustainability).",
            "items": { "$ref": "#/components/schemas/BrandClaim" }
          },
          "pricing": {
            "nullable": true,
            "description": "Store-level pricing summary aggregated from category pricing data.",
            "$ref": "#/components/schemas/StorePricing"
          },
          "api_version": { "type": "string" }
        }
      },
      "AIDescriptions": {
        "type": "object",
        "description": "Summary of how AI models describe this brand and where they disagree.",
        "properties": {
          "consensus_accuracy": {
            "type": "string",
            "nullable": true,
            "description": "Overall accuracy assessment of AI model consensus about this brand (e.g. 'High', 'Moderate', 'Low')."
          },
          "key_discrepancy": {
            "type": "string",
            "nullable": true,
            "description": "The most significant disagreement between AI models about this brand. This is the single most actionable insight for brand owners."
          }
        }
      },
      "Discoverability": {
        "type": "object",
        "description": "How visible this brand is across AI-generated query responses. Counts only — specific queries are gated.",
        "properties": {
          "queries_checked": {
            "type": "integer",
            "description": "Number of category-relevant queries tested for this brand."
          },
          "queries_present": {
            "type": "integer",
            "description": "Number of queries where this brand appeared in AI responses."
          },
          "gap_summary": {
            "type": "string",
            "nullable": true,
            "description": "Human-readable summary of why the brand is missing from certain queries."
          }
        }
      },
      "EntityContext": {
        "type": "object",
        "description": "Structural context about this brand's position in the corporate hierarchy.",
        "properties": {
          "entity_type": {
            "type": "string",
            "nullable": true,
            "enum": ["company", "product", "product_line", "feature", "acquired_brand"],
            "description": "What kind of entity this brand is."
          },
          "parent_brand": {
            "type": "object",
            "nullable": true,
            "description": "The parent company or brand, if this is a product or subsidiary.",
            "properties": {
              "name": { "type": "string" },
              "slug": { "type": "string" }
            }
          }
        }
      },
      "Timeliness": {
        "type": "object",
        "description": "Real-time brand health signals including narrative crisis status, recent social/news mentions, and AI fact-verification deltas.",
        "properties": {
          "signal_status": {
            "type": "string",
            "enum": ["none", "watch", "alert", "crisis"],
            "description": "Current narrative monitoring level."
          },
          "signal_status_since": { "type": "string", "format": "date-time", "nullable": true },
          "narrative_override": { "type": "string", "nullable": true },
          "archetype_override": { "type": "string", "nullable": true },
          "archetype_override_reason": { "type": "string", "nullable": true },
          "mention_baseline_7d": { "type": "number" },
          "recent_signals": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/SignalEvent" }
          },
          "delta_analysis": {
            "nullable": true,
            "$ref": "#/components/schemas/DeltaAnalysis"
          }
        }
      },
      "SignalEvent": {
        "type": "object",
        "properties": {
          "source": { "type": "string" },
          "sentiment": { "type": "string", "enum": ["positive", "neutral", "negative"], "nullable": true },
          "engagement": { "type": "integer" },
          "title": { "type": "string", "nullable": true },
          "url": { "type": "string", "format": "uri", "nullable": true },
          "detected_at": { "type": "string", "format": "date-time" }
        }
      },
      "DeltaAnalysis": {
        "type": "object",
        "properties": {
          "primary_delta": {
            "type": "object",
            "properties": {
              "pillar": { "type": "string" },
              "gap_type": { "type": "string" },
              "ai_claim": { "type": "string" },
              "ground_truth": { "type": "string" },
              "severity": { "type": "string" }
            }
          },
          "cross_model_consistency": { "type": "integer" },
          "inaccuracy_count": { "type": "integer" },
          "analysis_date": { "type": "string", "format": "date-time" }
      },
      "ContentStrategy": {
        "type": "object",
        "description": "Computed content strategy guidance based on the brand's AI representation gaps, readiness signals, and archetype benchmarks.",
        "properties": {
          "priority_actions": {
            "type": "array",
            "description": "Top 3 recommended actions to improve AI brand representation, ordered by impact.",
            "items": { "$ref": "#/components/schemas/PriorityAction" }
          },
          "readiness_gaps": {
            "type": "array",
            "description": "AI-readiness signals that are missing or inactive (e.g. 'structured_faq', 'schema_markup').",
            "items": { "type": "string" }
          },
          "archetype_playbook": {
            "type": "string",
            "description": "Lowercase archetype label for strategy mapping (e.g. 'challenger', 'phantom')."
          },
          "benchmark": { "$ref": "#/components/schemas/Benchmark" }
        }
      },
      "PriorityAction": {
        "type": "object",
        "properties": {
          "action": { "type": "string", "description": "Short action label (e.g. 'Fix category positioning')." },
          "why": { "type": "string", "description": "Human-readable explanation of why this action matters." },
          "content_type": { "type": "string", "description": "Suggested content format (e.g. 'pillar_page', 'faq_schema', 'comparison_page')." },
          "source": { "type": "string", "description": "Data source that triggered this action ('delta_analysis' or 'ai_readiness')." },
          "urgency": { "type": "string", "enum": ["critical", "important", "recommended"], "description": "Action urgency: 'critical' for active AI misrepresentation, 'important' for foundational gaps, 'recommended' for additional improvements." }
        }
      },
      "Benchmark": {
        "type": "object",
        "description": "How this brand compares to its archetype peers.",
        "properties": {
          "your_presence_rate": { "type": "integer", "description": "Percentage of checked queries where this brand appears." },
          "archetype_avg_presence_rate": { "type": "integer", "description": "Average presence rate for brands with the same archetype." },
          "your_readiness_signals": { "type": "integer", "description": "Number of active AI-readiness signals." },
          "max_readiness_signals": { "type": "integer", "description": "Total possible AI-readiness signals." }
        }
      },
      "CategoryPricing": {
        "type": "object",
        "description": "Pricing data for a specific product category within the brand's Shopify store.",
        "properties": {
          "category_name": { "type": "string", "description": "Product category name (e.g. 'Shoes', 'Socks', 'Apparel')." },
          "product_count": { "type": "integer", "description": "Number of products in this category." },
          "median_price_usd": { "type": "number", "description": "Median product price in USD." },
          "min_price_usd": { "type": "number", "description": "Lowest product price in USD." },
          "max_price_usd": { "type": "number", "description": "Highest product price in USD." },
          "price_tier": { "type": "string", "description": "Computed price tier (e.g. 'budget', 'mid-market', 'premium', 'ultra-premium')." },
          "sample_products": { "type": "array", "description": "Sample products (only available for claimed brands).", "items": { "type": "object" } }
        }
      },
      "BrandClaim": {
        "type": "object",
        "description": "A structured brand claim extracted from the profile narrative.",
        "properties": {
          "claim_type": { "type": "string", "enum": ["certification", "material", "sustainability", "award", "product", "differentiator", "market", "pricing", "funding"], "description": "Category of claim." },
          "claim_name": { "type": "string", "description": "Short label for the claim (e.g. 'B Corp Certified', 'Merino Wool')." },
          "claim_value": { "type": "string", "nullable": true, "description": "Additional detail about the claim." },
          "verified": { "type": "boolean", "description": "Whether this claim has been independently verified." },
          "confidence": { "type": "string", "description": "Extraction confidence level: 'high', 'medium', or 'low'." }
        }
      },
      "StorePricing": {
        "type": "object",
        "description": "Aggregated store-level pricing summary.",
        "properties": {
          "median_price_usd": { "type": "number", "description": "Weighted median price across all product categories." },
          "price_tier": { "type": "string", "description": "Overall price tier derived from the largest product category." },
          "product_count": { "type": "integer", "description": "Total number of products across all categories." },
          "source": { "type": "string", "description": "Data source identifier (currently 'shopify')." }
        }
      },
      "Vitals": {
        "type": "object",
        "description": "Structured business vitals extracted from the brand's homepage and public information.",
        "properties": {
          "core_products": { "type": "string", "nullable": true, "description": "Primary products or services offered." },
          "key_differentiator": { "type": "string", "nullable": true, "description": "What makes this brand different from competitors." },
          "pricing_model": { "type": "string", "nullable": true, "description": "Pricing structure (e.g. 'Subscription', 'DTC', 'Freemium')." },
          "target_markets": { "type": "string", "nullable": true, "description": "Primary customer segments or industries served." },
          "funding_stage": { "type": "string", "nullable": true, "description": "Funding stage or public status." },
          "founded": { "type": "string", "nullable": true, "description": "Year founded." },
          "headquarters": { "type": "string", "nullable": true, "description": "HQ location." },
          "employee_count": { "type": "string", "nullable": true, "description": "Approximate employee count." }
        }
      }
    }
  }
}
}