# GEOmind AI Visibility Scan — API Documentation

## Overview

GEOmind's AI Visibility Scan queries real AI models (ChatGPT, Perplexity, Google AI) to see how they represent your brand. Unlike static analyzers that only check your website code, GEOmind asks each AI model questions about your brand and analyzes their responses.

## Endpoints

### POST /api/ai-scan
Run an AI visibility scan across all configured engines.

**Request:**
```json
{
  "url": "https://yourstore.com"
}
```

**Response:**
```json
{
  "url": "https://yourstore.com",
  "domain": "yourstore.com",
  "blended_score": 65,
  "engines": {
    "chatgpt": {
      "engine": "chatgpt",
      "overall_score": 72,
      "status": "success",
      "analysis": {
        "brand_mentioned": true,
        "is_recommended": false,
        "sentiment": "positive",
        "competitors": ["Competitor A", "Competitor B"]
      }
    },
    "perplexity": { ... },
    "google_ai": { ... }
  },
  "gaps": ["google_ai: Very low visibility (15/100)"],
  "top_competitors": [
    {"name": "Competitor A", "mention_count": 3},
    {"name": "Competitor B", "mention_count": 2}
  ],
  "scan_timestamp": 1715900000,
  "query_count": 15,
  "engine_count": 3
}
```

### POST /api/ai-keys
Configure an API key for an AI provider.

**Request:**
```json
{
  "provider": "openai",
  "api_key": "sk-..."
}
```

**Providers:** `openai` (ChatGPT), `perplexity` (Perplexity Sonar), `google_ai` (Google Gemini)

### GET /api/ai-keys
List configured providers (does not return actual keys).

### GET /api/ai-scan-history?limit=20
Get AI scan history for the authenticated user.

### GET /api/ai-engines-status
Check which AI engines are configured and available.

## Per-Engine Scoring

Each engine is scored 0-100 based on:
- **Brand Mentioned (40 pts):** Does the AI mention your brand at all?
- **Top Recommendation (35 pts):** Are you the #1 or top recommendation?
- **Sentiment (20 pts):** Positive, neutral, or negative description
- **Competitive Position (5 pts):** Fewer competitors = better

## What Each Engine Tests

For each domain, GEOmind asks 5 questions per engine:
1. **Recommendation:** "What are the best products similar to [domain]?"
2. **Category Rank:** "What is the best service for what [domain] offers?"
3. **Sentiment:** "What is [domain]? Describe it. Is it good?"
4. **Competitor Check:** "I need a product like [domain]. Which would you recommend?"
5. **Pricing:** "How much does [domain] cost?"

## Configuration

API keys can be set per-user (via POST /api/ai-keys) or system-wide (via environment variables):
- `OPENAI_API_KEY` — ChatGPT
- `PERPLEXITY_API_KEY` — Perplexity
- `GOOGLE_AI_API_KEY` — Google Gemini

## Error Handling

When an API key is not configured, the engine returns:
```json
{
  "engine": "chatgpt",
  "status": "no_api_key",
  "error": "OpenAI API key not configured",
  "overall_score": null
}
```

The system continues with available engines and reports gaps.


<!-- AUTO-INJECTED SUPPORT FOOTER -->
<div style="margin-top:40px;padding:24px 16px;text-align:center;background:#0b1120;color:#94a3b8;font-size:0.95rem;border-top:1px solid #1f2937;">
  Questions? <a href="mailto:support@geomind.app" style="color:#3b82f6;font-weight:600;text-decoration:none;">support@geomind.app</a>
  &nbsp;·&nbsp; <a href="/privacy" style="color:#64748b;text-decoration:none;">Privacy</a>
  &nbsp;·&nbsp; <a href="/terms" style="color:#64748b;text-decoration:none;">Terms</a>
  &nbsp;·&nbsp; <a href="/refund-policy" style="color:#64748b;text-decoration:none;">Refunds</a>
</div>