What you can do
The API returns the same numbers as the CoreCited app. It is read-only: you can pull data into a dashboard, a client report, a spreadsheet or an alerting job, but you cannot yet create prompts or trigger runs through it.
| Endpoint | Returns |
|---|---|
GET /api/v1/brands | Every brand in the workspace, with the ids the other endpoints need. |
GET /api/v1/brands/{brandId}/visibility | The latest visibility score per engine, its drift band, the trend and sentiment. |
GET /api/v1/brands/{brandId}/stability | For every prompt and engine: who holds a durable position, and where your brand sits. |
GET /api/v1/brands/{brandId}/competitors | Your brand against each tracked competitor over 14 days, with confidence intervals. |
GET /api/v1/brands/{brandId}/sources | The domains AI answers cite, and which of them feed your competitors instead of you. |
GET /api/v1/brands/{brandId}/prompts | The buyer questions tracked for the brand, active and paused. |
Before you start
- API access is included on the Agency, Scale, Enterprise plans. On any other plan, every request returns
402 plan_required. - Only workspace Owners and Admins can create or revoke keys.
- Call the API from a server, a script or a scheduled job, never from a web page. The key gives read access to every brand in the workspace.
Quickstart
1. Create a key
In the app, open Team → API keys, name the key after what will use it (for example “Looker”), and press Create key. Copy it straight away. We store only a hash, so the key is shown once and can never be shown again.
2. Put it in an environment variable
export CORECITED_API_KEY="vis_…"Every example in these docs reads the key from CORECITED_API_KEY. Keep it out of source control.
3. List your brands
Every other endpoint takes a brand id. This call gets you one.
curl https://corecited.com/api/v1/brands \
-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", {
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",
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)4. Read a brand’s visibility
Put an id from step 3 in place of the one below.
curl https://corecited.com/api/v1/brands/7d1c2b9e-4a3f-4e61-9b2a-0c5d8e7f6a14/visibility \
-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/visibility", {
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/visibility",
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)The response is described field by field in Get visibility.
Basics
| Base URL | https://corecited.com |
| Methods | GET only |
| Format | JSON, UTF-8 |
| Success | { "data": … } |
| Failure | { "error": { "code", "message" } } |
| Auth | Bearer key |
| Machine-readable spec | OpenAPI 3.1 |
Versioning
The version is in the path: /api/v1. Within v1 we may add endpoints and add fields to responses. We will not remove a field, rename it or change its type. Write your client to ignore fields it does not recognise. Any breaking change will ship under a new version path, and every change is listed in the changelog.