The top 20 domains cited in the brand's answers over the last 14 days, sorted by gap: how many more competitor mentions than yours appeared in the answers that cited them.
A high gap is a lead. It points to a page that AI engines trust and that talks about your rivals, which makes it the place to get mentioned. Only web-grounded engines (Perplexity and Google's AI surfaces) return citations; ChatGPT, Claude and Gemini name brands without links.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
brandId | path | string (UUID) | A brand id from GET /api/v1/brands. |
Request
curl https://corecited.com/api/v1/brands/7d1c2b9e-4a3f-4e61-9b2a-0c5d8e7f6a14/sources \
-H "Authorization: Bearer $CORECITED_API_KEY"// Node 18+ (global fetch). Run server-side: the key must never reach a browser.
const res = await fetch("https://corecited.com/api/v1/brands/7d1c2b9e-4a3f-4e61-9b2a-0c5d8e7f6a14/sources", {
headers: { Authorization: `Bearer ${process.env.CORECITED_API_KEY}` },
});
const body = await res.json();
if (!res.ok) {
// Branch on body.error.code, never on the message text.
throw new Error(`${res.status} ${body.error.code}: ${body.error.message}`);
}
const { data } = body;
console.log(data);import os
import requests
res = requests.get(
"https://corecited.com/api/v1/brands/7d1c2b9e-4a3f-4e61-9b2a-0c5d8e7f6a14/sources",
headers={"Authorization": f"Bearer {os.environ['CORECITED_API_KEY']}"},
timeout=30,
)
body = res.json()
if not res.ok:
# Branch on body["error"]["code"], never on the message text.
raise RuntimeError(f"{res.status_code} {body['error']['code']}: {body['error']['message']}")
data = body["data"]
print(data)Response
200 OK with the fields below inside data. Numbers are JSON numbers, dates are strings, and a field listed as null-able is always present, holding null when there is no value.
| Field | Type | Description |
|---|---|---|
brand | object | The brand this response is about. |
brand.id | string | The brand's id. Use it in every /brands/{brandId}/… path. |
brand.name | string | The brand name as configured in CoreCited. |
brand.domain | string | The brand's website exactly as entered during setup. This is often a full URL such as https://www.example.com/, not a bare host. |
sources | object[] | The top 20 cited domains, biggest gap first, then most cited. Only web-grounded engines return citations. |
sources[].domain | string | The cited host, without www. |
sources[].count | number | Citations of this domain in successful runs over the last 14 days. |
sources[].sourceType | string | The most common classification of this domain's citations: ugc, forum, corporate, listicle, review, news, docs or other. |
sources[].competitorMentions | number | Competitor mentions in the answers that cited this domain. Each answer counts once per domain. |
sources[].brandMentions | number | Your brand's mentions in the answers that cited this domain. Each answer counts once per domain. |
sources[].gap | number | competitorMentions − brandMentions. A high gap marks a source that feeds your rivals and not you. |
sources[].isOwnDomain | boolean | True when the cited domain is your brand's own site. |
Example
{
"data": {
"brand": {
"id": "7d1c2b9e-4a3f-4e61-9b2a-0c5d8e7f6a14",
"name": "Acme Resume",
"domain": "https://www.acmeresume.com/"
},
"sources": [
{
"domain": "reddit.com",
"count": 18,
"sourceType": "forum",
"competitorMentions": 27,
"brandMentions": 2,
"gap": 25,
"isOwnDomain": false
},
{
"domain": "acmeresume.com",
"count": 6,
"sourceType": "corporate",
"competitorMentions": 3,
"brandMentions": 6,
"gap": -3,
"isOwnDomain": true
}
]
}
}Errors
| Status | Code | When |
|---|---|---|
| 401 | missing_key | No key was sent in Authorization or x-api-key. |
| 401 | invalid_key | The key is malformed, unknown, or has been revoked. |
| 402 | plan_required | The workspace is not on a plan that includes API access. This is checked on every request, so it also happens after a downgrade. |
| 404 | not_found | The brand id is not a UUID, does not exist, or belongs to another workspace. These cases are deliberately indistinguishable. |
| 429 | rate_limited | The workspace used up its requests for the current minute. All keys share one limit. |
| 500 | internal | Something failed on our side. The response carries no detail by design. |
Every error has the same body. See Errors for what to do about each one.
