{
  "openapi": "3.0.0",
  "info": {
    "title": "HighStory API",
    "description": "Public Machine-to-Machine API for HighStory AI Growth OS. AI agents (like Siri, Claude, OpenAI) can use these endpoints to perform SEO analysis, generate strategies, and read branding metrics.",
    "version": "1.0.0"
  },
  "externalDocs": {
    "description": "HighStory AI Growth OS Documentation",
    "url": "https://www.highstory.ai"
  },
  "servers": [
    {
      "url": "https://jeprtikkylotvcddrqvm.supabase.co/functions/v1",
      "description": "HighStory Live Supabase Edge Functions"
    }
  ],
  "paths": {
    "/run-public-analysis": {
      "post": {
        "summary": "Analyze site SEO & AEO (AI Visibility) metrics",
        "description": "Scrapes a client's website content, extracts basic target audience and suggested organic keywords via LLM, and calculates an AEO (AI Visibility) score using live Perplexity search mentions.",
        "operationId": "runPublicAnalysis",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "The URL of the client website to analyze",
                    "example": "https://www.example.com"
                  }
                },
                "required": [
                  "url"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful site analysis",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "site_summary": {
                          "type": "string"
                        },
                        "business_type": {
                          "type": "string"
                        },
                        "estimated_avg_cart": {
                          "type": "integer"
                        },
                        "conversion_rate_benchmark": {
                          "type": "number"
                        },
                        "monthly_organic_visits_per_article": {
                          "type": "integer"
                        },
                        "suggested_keywords": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "keyword": {
                                "type": "string"
                              },
                              "estimated_monthly_volume": {
                                "type": "integer"
                              },
                              "difficulty": {
                                "type": "string"
                              },
                              "intent": {
                                "type": "string"
                              }
                            }
                          }
                        },
                        "url": {
                          "type": "string"
                        },
                        "analyzed_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "ai_visibility": {
                          "type": "object",
                          "properties": {
                            "score": {
                              "type": "integer",
                              "description": "AI visibility score (AEO check, 0 to 100)"
                            },
                            "mentions": {
                              "type": "integer"
                            },
                            "total_sources": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/generate-strategy": {
      "post": {
        "summary": "Generate an AI strategic marketing plan",
        "description": "Trigger the multi-agent pipeline to generate a comprehensive social media and search engine visibility strategy for a client's brand.",
        "operationId": "generateStrategy",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "The brand's website URL",
                    "example": "https://example.com"
                  },
                  "languages": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Target languages for localized content strategy",
                    "example": ["fr", "en"]
                  }
                },
                "required": [
                  "url"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Strategy generated successfully"
          }
        }
      }
    },
    "/get-brand-profile": {
      "post": {
        "summary": "Fetch parsed brand style and visual identity profile",
        "description": "Extracts and returns the analyzed aesthetic era, primary/secondary colors, typography, brand tone, and vocabulary guidelines for a website.",
        "operationId": "getBrandProfile",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "Website URL of the analyzed brand"
                  }
                },
                "required": [
                  "url"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Detailed brand styling profile metadata"
          }
        }
      }
    }
  }
}