Brands & markets

A brand is what Skoup measures: its offerings and its presence in AI answers. A solo workspace holds one brand; an agency workspace holds one brand per client, each fully isolated. Almost every call of the API is scoped to a brand: its id (br_…) is in the URL, /v1/brands/{brand}/….

A brand is measured on one or more markets — a country, with its language and currency. The AI assistants do not answer the same way in France and in the US, so every measurement (visibility, readiness, revenue…) is per market. One market is the brand’s primary market: it is the default whenever a call accepts a market parameter and you leave it out.

Verticals

A brand has a vertical — what it sells — that decides which modules apply to it:

`vertical`	The brand	Modules that do not exist for it
`ecommerce`	Online store: a store or a feed synced into a catalogue	—
`saas`	Software or an online service: plans and offerings, declared by hand or read on its site	Catalogue sync, variants, attributed orders and revenue, revenue correlation, write-backs, the feed and checkout blocks of readiness, the availability alert
`local`	A local business or practice (a practice, an agency, a shop): its services on site	The same as `saas`

An endpoint of a module the vertical lacks answers 403 capability_unavailable: nothing to fix on the key or the plan, the module does not exist for that brand. Read vertical on the brand before calling a store’s endpoints.

Establishments

A local brand has one or more establishments (loc_…) — a chain of practices, stores or agencies is one brand with that many establishments, the market staying a country. Each establishment carries its name, city, address, phone, opening hours and the page that describes it on the site. Skoup reads them on the brand’s site (establishment pages and their LocalBusiness markup) or gets them in the app; tracked says whether the query panel writes queries for it.

Every query of a local brand is asked from the city of one establishment (location on the query), and the wrong_local_fact alert judges an address or a phone against the establishment the answer was about (location on the alert) — one alert per establishment.

I want to…	Call
List the establishments of a brand	`GET /v1/brands/{brand}/locations`
Those of one market, tracked only	`GET /v1/brands/{brand}/locations?market=FR&tracked=true`

A market’s locality field is still served for compatibility (the first tracked establishment of the market, null without any): prefer /locations. Establishments are managed in the app (markets step, Establishments page), not through the API.

Statuses of a market

offactive

active = measured every week. off = not measured; a market that has a history is kept, never deleted. backfill is a transitional value of the same field.

I want to…

I want to…	Call
List the brands my key can reach	`GET /v1/brands`
Read one brand	`GET /v1/brands/{brand}`
List a brand’s markets	`GET /v1/brands/{brand}/markets`
List only the measured markets	`GET /v1/brands/{brand}/markets?status=active`

Scope: brands:read. Events: none — brands and markets are managed in the Skoup app.

Scenario: find the brand and its markets

Every integration starts here: resolve the brand id once, store it, and read its active markets.


curl https://api.skoup.ai/v1/brands \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"
 
curl "https://api.skoup.ai/v1/brands/br_034PJIMnN3EOTCU3TMUdLS/markets?status=active" \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"

Pitfalls

Ids are opaque. Store br_… as a string; never build it from the brand’s name or slug.
A key may be limited to some brands. A brand outside the key’s selection answers 404 resource_missing, exactly like a brand that does not exist.
Test keys see the sandbox brands, not yours: the ids differ between test and live.