# BuildSOM API
# Version: 1.0
# Base URL: https://www.buildsom.com
# Description: Public dashboard and project management APIs for brand AI visibility monitoring.
# Maintained by: BuildSOM (https://buildsom.com)

## Authentication
# Dashboard reads: GET /api/public-dashboard/* — Authorization: Bearer <YOUR_API_KEY>
# Project writes: POST /api/public-project/* — same Bearer key
# Generate the key in the BuildSOM dashboard under Project Settings -> API.
# Each key is unique per (user, project) and does not expire. Rotate from
# the same screen ("Regenerate"); the previous key is invalidated immediately.

## Shared Filter Parameters (all GET /api/public-dashboard/* endpoints)
# timePeriod  (required) - "Last 7 Days" | "Last 30 Days"
# region      (optional) - ISO country/region code, e.g. "US", "HK"
# aiPlatform  (optional) - "ChatGPT" | "Perplexity" | "Copilot" | "Gemini" | etc.
# promptTag   (optional) - tag string to filter monitoring prompts
# Note: userEmail / projectName are NOT required - the API key resolves the (user, project) scope.

## Response Shape
# All endpoints return HTTP 200 with JSON:
#   { "projectName": "...", "data": [...] }
# Exception: /kpi-cards returns "kpiCards" object, not "data"
# Exception: /ugc-source-analysis returns platformSummary + topInfluencers, not "data"

## Error Shape
#   { "message": "Invalid API key" }

## KPI & Distribution Endpoints
GET /api/public-dashboard/kpi-cards
  Intent: Retrieve headline KPI metrics for a project.
  Returns: { kpiCards: { geoImpactScore, brandCoverage, avgPosition, shareOfVoice } }

GET /api/public-dashboard/brand-coverage-overtime
  Intent: Fetch daily brand coverage time series for trend analysis.
  Returns: { data: [{ date, <brandName>: coveragePct }] }

GET /api/public-dashboard/brand-coverage-rank
  Intent: Get ranked coverage comparison between brand and competitors.
  Returns: { data: [{ name, coverage, changeRate, avgPosition, isOwnBrand }] }

GET /api/public-dashboard/citation-sources-distribution
  Intent: Understand which content types AI platforms cite most.
  Returns: { data: [{ name, value, count }] }

GET /api/public-dashboard/competitive-landscape
  Intent: Get the full competitive position matrix (visibility vs. avg position).
  Returns: { data: [{ name, visibility, avgPosition, mentions }] }

## Insight & Citation Endpoints
GET /api/public-dashboard/top-performing-prompts
  Intent: Identify which monitoring queries drive the most brand visibility.
  Returns: { data: [{ prompt, coverage, avgPosition }] }

GET /api/public-dashboard/top-citations-url
  Intent: Find the exact URLs AI platforms cite in brand-relevant responses.
  Returns: { data: [{ source (URL), coverage, type: "url" }] }

GET /api/public-dashboard/top-citations-domain
  Intent: Aggregate citation data by root domain.
  Returns: { data: [{ source (domain), coverage, type: "domain" }] }

GET /api/public-dashboard/prompt-performance-matrix
  IMPORTANT: Only accepts timePeriod.
  Do NOT pass region, aiPlatform, or promptTag to this endpoint.
  Intent: Get a prompt x platform matrix showing per-platform brand mention flags.
  Returns: { prompts: [{ id, text }], platforms: [string] }

GET /api/public-dashboard/ugc-source-analysis
  Intent: UGC Source Analysis — social/UGC citation distribution and top creators.
  Optional: ugcPlatformKey (e.g. youtube, instagram) to filter one platform.
  Returns: { platformSummary, topInfluencers, totalSocialCitationCount, totalMergedInfluencerCount, coreMetricTrends? }

## Recommended Workflow for AI Agents
1. GET /api/public-dashboard/kpi-cards               -> summary KPI overview
2. GET /api/public-dashboard/brand-coverage-overtime -> trend direction
3. GET /api/public-dashboard/competitive-landscape   -> competitive position
4. GET /api/public-dashboard/brand-coverage-rank     -> ranking with change rates
5. GET /api/public-dashboard/top-performing-prompts  -> best-performing queries
6. GET /api/public-dashboard/prompt-performance-matrix -> platform-level detail
7. GET /api/public-dashboard/ugc-source-analysis     -> UGC / social citation sources

## Project Management Endpoints (POST, JSON body)
# Same Bearer API key. Add-competitors and add-prompts apply to the project bound to the key.
# Create-project uses the key owner (any project key for that user) and returns a new project API key.
# Plan limits (projects, prompts, competitors, domains, aliases) are enforced per subscription.

POST /api/public-project/projects
  Intent: Create a project with optional brand domains, brand aliases, competitors, and prompts.
  Body: { name, region?, language?, brandAliases?, domains?, competitors?, prompts? }
  Returns: { project, apiKey, domains, competitors, prompts, remainingPromptDaily? }

POST /api/public-project/competitors
  Intent: Add competitors (with optional domains/aliases) to the API key's project.
  Body: { competitors: [{ name, domain?, domains?, aliases? }] }
  Returns: { projectId, projectName, competitors, createdCount, updatedCount }

POST /api/public-project/prompts
  Intent: Add monitoring prompts to the API key's project.
  Body: { prompts: [{ text, tags?, region?, language? }] }
  Returns: { projectId, projectName, prompts, createdIds, remaining }

## Error Codes
200: Success
400: Missing or invalid query parameter - read the "message" field
401: API key missing or invalid - confirm it has not been regenerated
403: Account inactive, plan limit reached, or sanity-check params don't match the API key's scope
429: Daily prompt addition limit reached (project management prompt endpoints)
404: Project bound to the API key no longer exists
500: Internal server error - retry after a short delay