API Documentation

APIs, documentation, and tools. Build integrations and automations with BuildSOM's public APIs — read dashboard metrics and manage projects, competitors, and prompts programmatically. Designed for both human developers and AI agents.

Authentication

Shared Query Parameters

| Parameter | Required | Example | Description | | --- | --- | --- | --- | | timePeriod | yes | Last 360 Days | Dashboard-type APIs allow Today / Last 7 Days / Last 30 Days / Last 90 Days / Last 360 Days. List-type APIs allow Today only. | | region | no | US | ISO country/region code, e.g. US, HK | | language | no | en | Prompt language code, e.g. en, zh-hk, zh-cn | | aiPlatform | no | ChatGPT | ChatGPT · Perplexity · Copilot · Gemini · etc. | | promptTag | no | Custom | Tag string for filtering monitoring prompts |

KPI & Distribution APIs

KPI Cards

Total Hits Overtime

Brand Coverage Overtime

Competitor Comparison

Citation Sources Distribution

Competitive Landscape

Insight & Citation APIs

Top Performing Prompts

Top Citations (URL)

Top Citations (Domain)

Prompt Performance Matrix

UGC Source Analysis

Missed GEO Opportunity

Missed SEO Opportunity

Competitor Analysis

Project Management APIs

Create Project

Add Competitors

Add Prompts

For AI Agents

Instructions for AI Agents

1. Provision a project API key from Project Settings → API in the BuildSOM dashboard. The key is unique per (user, project) and does not expire — store it as a secret in your environment. 2. All /api/public-dashboard/ endpoints are GET requests with query parameters only — no request body. 3. /api/public-project/ endpoints are POST requests with a JSON body and the same Bearer API key. 4. Send the key on every request as Authorization: Bearer <YOUR_API_KEY>. Dashboard reads use the project bound to the key; create-project uses any key for that user to provision a new project. 5. timePeriod is required. Dashboard-type APIs accept exactly "Today", "Last 7 Days", "Last 30 Days", "Last 90 Days", or "Last 360 Days". List-type APIs accept exactly "Today". 6. region, language, aiPlatform, and promptTag are optional. Omit them for unfiltered results across all regions, languages, and platforms. 7. The Prompt Performance Matrix accepts region, language, aiPlatform, and promptTag. Missed GEO Opportunity and Missed SEO Opportunity accept region, language, and promptTag, but do not accept aiPlatform. 8. KPI Cards response uses the key kpiCards (not data) with totalHits, brandCoverage, avgPosition, shareOfVoice, and trends. UGC Source Analysis returns platformSummary and topInfluencers. SEO Insights returns topRanking and/or positionTracking. Competitor Analysis is a two-step flow: call without competitorId to list competitors, then call again with competitorId to get citations and webMonitor (response still includes the competitors list). All other dashboard endpoints return a data array. 9. On 401, the key is missing or invalid — re-read it from Project Settings → API and confirm it has not been regenerated. 10. On 400, parse the message field to identify which query parameter is missing or invalid. 11. Every call counts against Public API quota. Paid plans include 100 free calls per endpoint per day (resets 00:00 GMT+8); after that, calls use the prepaid call balance, auto-recharged from the card on file up to the daily auto-recharge budget set in Billing. 12. On 403, read the code field: PLAN_REQUIRED means the account needs a paid plan; API_DISABLED means API access is turned off in Billing. Do not retry until the account owner fixes it. 13. On 402, read the code field: PAYMENT_METHOD_REQUIRED means today's free quota for that endpoint is used up and no payment method is on file; PAYMENT_FAILED means the automatic top-up charge failed. Ask the account owner to update Billing. 14. On 429 with code BUDGET_EXCEEDED, today's auto-recharge budget is used up — stop calling until 00:00 GMT+8 or until the budget is raised in Billing.

Recommended API Workflow

1. GET /api/public-dashboard/kpi-cards — Retrieve the 4 headline KPIs (Total Hits, Brand Coverage, Avg Position, Share of Voice). Use as the summary before drilling into details. 2. GET /api/public-dashboard/hits-overtime — Fetch daily Total Hits for the brand to understand mention volume over time. 3. GET /api/public-dashboard/brand-coverage-overtime — Fetch the daily coverage time series to understand trend direction (rising vs. declining). 4. GET /api/public-dashboard/competitive-landscape — Get the full competitive position matrix — visibility vs. avg position for all competitors. 5. GET /api/public-dashboard/competitor-comparison — Confirm ranking order and inspect difference to surface significant shifts. 6. GET /api/public-dashboard/top-performing-prompts — Identify which monitoring queries drive the most brand visibility in AI responses. 7. GET /api/public-dashboard/prompt-performance-matrix — Get per-platform detail for each prompt. List-type API: timePeriod supports Today only. Supports optional region, language, aiPlatform, and promptTag filters. 8. GET /api/public-dashboard/missed-geo-opportunity — List prompts that lack coverage on one or more AI platforms (Missed GEO Opportunity). List-type API: timePeriod supports Today only. Supports optional region, language, and promptTag filters. Do not pass aiPlatform. 9. GET /api/public-dashboard/missed-seo-opportunity — List keywords whose brand is not in Google organic Top 10 (Missed SEO Opportunity). Supports optional region, language, and promptTag filters. 10. GET /api/public-dashboard/ugc-source-analysis — Analyze UGC and social citation sources — platform mix, top creators, and period-over-period amplification trends. 11. GET /api/public-dashboard/competitor-analysis — Two-step: (1) list competitors to obtain id, (2) pass competitorId to load citations and Web Monitor diffs. 12. GET /api/public-dashboard/seo-insights — Fetch Google SERP coverage (top ranking). List-type API: timePeriod supports Today only. Pass view=position-tracking or view=all for Position Tracking.