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.
- Base URL: https://buildsom.com
- Version: 1.0
Authentication
- Dashboard reads:
GET /api/public-dashboard/*withAuthorization: Bearer <YOUR_API_KEY> - Project writes:
POST /api/public-project/*with the same Bearer key - Generate the key in Project Settings → API
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
- Nav label: KPI Cards
- Method: GET
- Endpoint:
/api/public-dashboard/kpi-cards - Use case: Return the 4 KPI cards (Total Hits, Brand Coverage, Avg Position, Share of Voice) for the project bound to the API key.
- Sample output:
{"projectName":"My Brand","kpiCards":{"totalHits":120,"brandCoverage":60,"avgPosition":2.4,"shareOfVoice":30,"trends":{"totalHits":{"diff":20,"current":120,"percent":20,"previous":100},"brandCoverage":{"diff":10,"current":60,"percent":20,"previous":50},"avgRankingPosition":{"diff":-0.6,"current":2.4,"percent":-20,"previous":3},"shareOfVoice":{"diff":5,"current":30,"percent":20,"previous":25}}}}
Total Hits Overtime
- Nav label: Total Hits Overtime
- Method: GET
- Endpoint:
/api/public-dashboard/hits-overtime - Use case: Return daily Total Hits Overtime for the brand bound to the API key. Each Hit is a verified brand mention on a target AI platform for a specific prompt on one calendar day.
- Sample output:
{"projectName":"My Brand","data":[{"date":"2026-04-01","hits":12},{"date":"2026-04-02","hits":15}]}
Brand Coverage Overtime
- Nav label: Coverage Overtime
- Method: GET
- Endpoint:
/api/public-dashboard/brand-coverage-overtime - Use case: Return Brand Coverage Overtime for the project bound to the API key.
- Sample output:
{"projectName":"My Brand","data":[{"date":"2026-04-01","My Brand":28.9,"c1":30.6,"c2":13.8},{"date":"2026-04-02","My Brand":39.2,"c1":30.4,"c2":12.5}]}
Competitor Comparison
- Nav label: Competitor Comparison
- Method: GET
- Endpoint:
/api/public-dashboard/competitor-comparison - Use case: Return Competitor Comparison for the project bound to the API key.
- Sample output:
{"projectName":"My Brand","data":[{"name":"My Brand","coverage":45.2,"difference":3.1,"avgPosition":2.1,"isOwnBrand":true}]}
Citation Sources Distribution
- Nav label: Citation Sources
- Method: GET
- Endpoint:
/api/public-dashboard/citation-sources-distribution - Use case: Return Citation Sources Distribution for the project bound to the API key.
- Sample output:
{"projectName":"My Brand","data":[{"name":"Direct","value":3,"count":2807},{"name":"Competitor","value":3,"count":2931},{"name":"Others","value":94,"count":103573}]}
Competitive Landscape
- Nav label: Competitive Landscape
- Method: GET
- Endpoint:
/api/public-dashboard/competitive-landscape - Use case: Return Competitive Landscape for the project bound to the API key.
- Sample output:
{"projectName":"My Brand","data":[{"name":"My Brand","shareOfVoice":38.3,"avgPosition":1.3,"size":300,"color":"#4f46e5","type":"own"},{"name":"competitor1","shareOfVoice":1.7,"avgPosition":2.4,"size":200,"color":"#f59e0b","type":"competitor"}]}
Insight & Citation APIs
Top Performing Prompts
- Nav label: Top Prompts
- Method: GET
- Endpoint:
/api/public-dashboard/top-performing-prompts - Use case: Return Top Performing Prompts for the project bound to the API key. List-type API: timePeriod supports Today only.
- Sample output:
{"projectName":"My Brand","data":[{"prompt":"What are the best brands to consider?","coverage":82,"avgPosition":1.8,"promptId":"...","region":"US"}]}
Top Citations (URL)
- Nav label: Top Citations (URL)
- Method: GET
- Endpoint:
/api/public-dashboard/top-citations-url - Use case: Return Top Citations Analysis (By URL) for the project bound to the API key. List-type API: timePeriod supports Today only.
- Sample output:
{"projectName":"My Brand","data":[{"source":"https://www.mybrand.com/erp","coverage":18.5,"type":"url"}]}
Top Citations (Domain)
- Nav label: Top Citations (Domain)
- Method: GET
- Endpoint:
/api/public-dashboard/top-citations-domain - Use case: Return Top Citations Analysis (By Domain) for the project bound to the API key. List-type API: timePeriod supports Today only.
- Sample output:
{"projectName":"My Brand","data":[{"source":"mybrand.com","coverage":42.3,"type":"domain"}]}
Prompt Performance Matrix
- Nav label: Prompt Performance Matrix
- Method: GET
- Endpoint:
/api/public-dashboard/prompt-performance-matrix - Use case: Return Prompt Performance Matrix for the project bound to the API key. List-type API: timePeriod supports Today only. Optional region, language, aiPlatform, and promptTag filters match the dashboard.
- Sample output:
{"projectName":"My Brand","timePeriod":"Today","prompts":[{"id":"pr1","text":"Best ERP in US"}],"platforms":["ChatGPT","Perplexity"]}
UGC Source Analysis
- Nav label: UGC Source Analysis
- Method: GET
- Endpoint:
/api/public-dashboard/ugc-source-analysis - Use case: Return UGC Source Analysis for the project bound to the API key — platform citation distribution, top creators/sources, and amplification metrics. List-type API: timePeriod supports Today only. Optional ugcPlatformKey filters to one social platform.
- Sample output:
{"projectName":"My Brand","platformSummary":[{"platformKey":"youtube","platformLabel":"YouTube","citationCount":42}],"topInfluencers":[{"platformKey":"youtube","handle":"creator","citationCount":12,"sampleUrls":["https://youtube.com/watch?v=abc"]}],"totalSocialCitationCount":120,"totalMergedInfluencerCount":35,"topInfluencerDisplayCap":50}
Missed GEO Opportunity
- Nav label: Missed GEO Opportunity
- Method: GET
- Endpoint:
/api/public-dashboard/missed-geo-opportunity - Use case: Return Missed GEO Opportunity prompts for the project bound to the API key — monitoring prompts that lack coverage on one or more AI platforms. List-type API: timePeriod supports Today only. Supports optional region, language, and promptTag filters like the dashboard. aiPlatform is not accepted on this endpoint.
- Sample output:
{"projectName":"My Brand","timePeriod":"Today","data":[{"promptId":"pr1","promptText":"What are the best brands to consider?","tags":["Custom"],"region":"US","language":"en","qualifiedPlatforms":[{"aiCode":"chatgpt","displayName":"ChatGPT"}]}]}
Missed SEO Opportunity
- Nav label: Missed SEO Opportunity
- Method: GET
- Endpoint:
/api/public-dashboard/missed-seo-opportunity - Use case: Return Missed SEO Opportunity keywords for the project bound to the API key — prompts (keywords) whose brand is not in Google organic Top 10 for the selected period. List-type API: timePeriod supports Today only. Supports optional region, language, and promptTag filters like the dashboard.
- Sample output:
{"projectName":"My Brand","timePeriod":"Today","data":[{"promptId":"pr1","keyword":"What are the best brands to consider?","tags":["Custom"],"region":"US","language":"en","bestAvgPosition":null,"rankingUrl":null}]}
Competitor Analysis
- Nav label: Competitor Analysis
- Method: GET
- Endpoint:
/api/public-dashboard/competitor-analysis - Use case: Competitor Analysis uses a two-step flow. First retrieve the project's competitors, then use a returned competitor ID to request detailed analysis. List-type API: timePeriod supports Today only.
- Sample output:
{"projectName":"My Brand","timePeriod":"Today","competitors":[{"id":"c1","name":"Rival Co"},{"id":"c2","name":"Rival2 Co"}]}
Project Management APIs
Create Project
- Nav label: Create Project
- Method: POST
- Endpoint:
/api/public-project/projects - Use case: Create a new project for the API key owner with optional brand domains, brand aliases, competitors (with domains/aliases), and prompts. Plan limits from your subscription apply.
- Sample output:
{"project":{"id":"...","userId":"...","name":"My Brand","brandAlias":["MyBrand Inc"],"brandAliasUpdatedAt":null,"consolidatedBrandAliases":null,"previousBrandName":null,"description":null,"industry":null,"region":"US","language":"en","keywordArray":null,"onboardingCompetitorStepPending":false,"onboardingIntermediateNoticeClearedAt":null,"isOrderHolding":false,"createdAt":"2026-10-01T08:00:00.000Z","updatedAt":"2026-10-01T08:00:00.000Z"},"apiKey":"bsom_boutir_...","domains":{"created":["mybrand.com"],"skipped":[]},"competitors":[{"id":"...","projectId":"...","name":"Rival Co","domain":"rival.com","domains":["rival.com"],"aliases":["Rival"],"createdAt":"2026-10-01T08:00:01.000Z"}],"prompts":[{"id":"...","projectId":"...","competitorId":null,"text":"What are the best brands to consider?","tags":["Custom"],"region":"US","language":"en","competitorExtractionOnly":false,"orderTrackingOnly":false,"createdAt":"2026-10-01T08:00:02.000Z"}]}
Add Competitors
- Nav label: Add Competitors
- Method: POST
- Endpoint:
/api/public-project/competitors - Use case: Add one or more competitors to the project bound to the API key. Optional domains and aliases per competitor; competitor limits apply per plan.
- Sample output:
{"projectId":"...","projectName":"My Brand","competitors":[{"id":"...","projectId":"...","name":"Rival Co","domain":"rival.com","domains":["rival.com"],"aliases":["Rival"],"createdAt":"2026-10-01T08:00:00.000Z"}],"createdCount":1,"updatedCount":0}
Add Prompts
- Nav label: Add Prompts
- Method: POST
- Endpoint:
/api/public-project/prompts - Use case: Add monitoring prompts to the project bound to the API key. Each prompt requires text, region, and language; tags are optional. Prompt plan limits and daily addition caps apply.
- Sample output:
{"projectId":"...","projectName":"My Brand","prompts":[{"id":"...","projectId":"...","competitorId":null,"text":"What are the best brands to consider?","tags":["Custom"],"region":"US","language":"en","competitorExtractionOnly":false,"orderTrackingOnly":false,"createdAt":"2026-10-01T08:00:00.000Z"}],"createdIds":["..."]}
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.