REST API

Read your brands' AI-visibility metrics, cited sources and actions over HTTP with a personal API key.

Base URL and authentication

https://www.heynotable.com/api/v1

Send your API key on every request (how to get one):

curl -H "Authorization: Bearer $NOTABLE_KEY" https://www.heynotable.com/api/v1/brands

Responses and errors

Every response is JSON: { "data": … } on success, { "error": { "code", "message" } } otherwise.

Status	When
`400`	A parameter or body is not valid
`401`	No key, or a key that is revoked or unknown
`404`	No such brand or action, or one your key cannot see (never `403`, so ids are not confirmed)
`429`	More than 120 requests a minute on this key; retry after the `Retry-After` header (60 seconds)

Endpoints

Method	Path	Returns
GET	`/brands`	Every brand you can see, across your workspaces
GET	`/brands/{brandId}`	Market, competitors and intents (with their ids), and your role
GET	`/brands/{brandId}/metrics`	The latest 28-day window, for the brand and each competitor
GET	`/brands/{brandId}/trend`	One metric over time
GET	`/brands/{brandId}/sources`	Cited domains, and those cited for competitors but not you
GET	`/brands/{brandId}/actions`	What to work on next, highest priority first
PATCH	`/brands/{brandId}/actions/{actionId}`	Mark an action done, dismissed or to do again

List brands

GET /brands. Each brand has id, name, website, workspaceId, workspaceName, marketCountry, marketLanguage, collectionPaused and createdAt. Start here to get brand ids.

Get a brand

GET /brands/{brandId}. The brand's market, ownedDomains, yourRole, and its competitors and intents with their ids, which the filters below take.

Metrics

GET /brands/{brandId}/metrics?intent=&engine=

Parameter
`intent`	Optional. One intent id; all intents together when left out
`engine`	Optional. One engine id; all engines pooled when left out

Returns windowEnd, windowDays (28), methodologyVersion, enginesWithData, and entities: the brand (isBrand: true) and each competitor, each with all four metrics.

Every metric is a rate:

{
  "value": 0.42,
  "lower": 0.35,
  "upper": 0.49,
  "n": 180,
  "insufficient": null,
  "significantChange": 0.07
}

value, lower, upper: a fraction 0–1 and its 95% interval.
n: how many answers it is based on.
insufficient: null, or why there is no number (no_data, small_sample, wide_interval), in which case value is null.
significantChange: the change against the four weeks before, only when it is statistically significant; otherwise null.

Trend

GET /brands/{brandId}/trend?metric=answer_share&days=90

Parameter
`metric`	`answer_share` (default), `pick_rate`, `citation_rate` or `top_three_rate`
`days`	7 to 365; 90 by default

Returns one series per entity (the brand and each competitor) of rates over time.

Sources

GET /brands/{brandId}/sources?intent=&engine= takes the same filters as metrics. Returns the domains the assistants cited in answers about your market, and forCompetitorsNotYou: third-party sites cited when a competitor is recommended and you are not. That second list is your outreach list.

Actions

GET /brands/{brandId}/actions?status=todo lists actions, highest priorityScore first, each with its key, status, evidenceStrength, the intentIds and engines it concerns, and updatedAt. status is optional: todo, done or dismissed.

PATCH /brands/{brandId}/actions/{actionId} changes one action's status. It needs a role that can edit the brand.

curl -X PATCH \
  -H "Authorization: Bearer $NOTABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"done"}' \
  https://www.heynotable.com/api/v1/brands/BRAND_ID/actions/ACTION_ID

Values

Metrics: answer_share, pick_rate, citation_rate, top_three_rate (what each means).
Engines: chatgpt, aio, ai_mode, gemini, perplexity, copilot, claude.
Action statuses: todo, done, dismissed.