Shelf

Endpoints

GET/v1/brands/{brand}/shelf

L’objet Shelf item

Attributs

objectstring
shelf_item
idstring
The product (prod_…) or the establishment (loc_…).
kindenum
What a line of the shelf is: a catalogue product (an offer for a SaaS brand — the word changes, not the object) or an establishment of a local brand.
Valeurs possibles : product · location
titlestring
categorystringnullable
The product's category — the city of an establishment.
image_urlstringnullable
pricestringnullable
Decimal string, in currency.
currencystringnullable
urlstringnullable
stateenum
The state of one line of the shelf of the home — a product (an establishment for a local brand) as the assistants treat it on a market. Decided by Visibility\Services\ShelfStateJudge alone, never by the front; the thresholds live in config('skoup.visibility.shelf'). | | |---| | error « Une IA se trompe »: an open alert on it, or a false verdict of its perception. | | absent « Absent »: its queries were asked, no answer named it. | | reinforce « À renforcer »: cited, but a differentiator does not come through or its perception is weak. | | good « Bien cité ». | | unmeasured « Pas encore mesuré »: no answer on its queries over the period. |
Valeurs possibles : error · absent · reinforce · good · unmeasured
state_reasonobject
Afficher les attributs enfants
- kindenumnullable
 Why a line of the shelf is in its state — the short reason the front words (« Prix faux · ChatGPT », « Absent · 6 requêtes », « À renforcer · USP absente »). A good or unmeasured line has none. | | |---| | alert An open alert on the product / establishment (price, stock, invented spec, local fact). | | perception_false A perception gap judged false (a spec, the price…) not carried by an alert. | | never_cited Its queries were asked, no answer named it. | | usp_absent A differentiator of its sheet missing from too many of the answers. | | weak_perception Its perception score is under the threshold. |
 Valeurs possibles : alert · perception_false · never_cited · usp_absent · weak_perception
- modelstringnullable
- alert_kindstringnullable
- elementstringnullable
- labelstringnullable
- countintegernullable
 Occurrences of the alert · answers of the false verdict · queries never citing it · differentiators absent · the weak score.
sharenumbernullable
Share of the answers to its queries naming it over the period, in %, every measured model. null = never measured, never 0.
deltanumbernullable
Points gained or lost between the last two weekly cycles, every measured model. null without a previous cycle.
by_modelarray of object
Afficher les attributs enfants
- modelstring
- runsinteger
- hitsinteger
- positionnumbernullable
trendarray of object
Afficher les attributs enfants
- week_starts_onstring
- by_modelarray of object
  Afficher les attributs enfants
  - modelstring
  - runsinteger
  - hitsinteger
prompt_countinteger
leaderobjectnullable
The competitor recommended first most often on its queries.
Afficher les attributs enfants
- namestring
- brand_namestring
perception_scoreintegernullable
Conforming ÷ verdicts, 0–100; null before enough judged answers.
ai_revenueobjectnullable
null without store orders.
Afficher les attributs enfants
- amountnumber
- currencystring
- ordersinteger
open_fixesinteger
Its open lines in the inbox.
livemodeboolean
true pour les données réelles, false pour le bac à sable du mode test.

L'objet Shelf item


{
  "object": "shelf_item",
  "id": "prod_5ZbXo1Z0hYV8sQnA3x1m2c",
  "kind": "product",
  "title": "Grizl CF SL 7",
  "category": "string",
  "image_url": "string",
  "price": "string",
  "currency": "EUR",
  "url": "https://hooks.example.com/skoup",
  "state": "error",
  "state_reason": {
    "kind": "alert",
    "model": "string",
    "alert_kind": "string",
    "element": "string",
    "label": "string",
    "count": 12
  },
  "share": 27.5,
  "delta": 27.5,
  "by_model": [
    {
      "model": "string",
      "runs": 12,
      "hits": 12,
      "position": 27.5
    }
  ],
  "trend": [
    {
      "week_starts_on": "2026-09-21",
      "by_model": [
        {
          "model": "string",
          "runs": 12,
          "hits": 12
        }
      ]
    }
  ],
  "prompt_count": 12,
  "leader": {
    "name": "Nordvelo",
    "brand_name": "string"
  },
  "perception_score": 12,
  "ai_revenue": {
    "amount": 27.5,
    "currency": "EUR",
    "orders": 12
  },
  "open_fixes": 12,
  "livemode": true
}

List the shelf

GET/v1/brands/{brand}/shelf

Every tracked product of the brand on a market — every establishment for a local brand — with how the AI assistants treat it, in the order to look at them: the products an assistant gets wrong first, then the absent ones, the ones to reinforce, the unmeasured, the good; inside a state, the AI revenue then the share. The home screen of the app. Before the first completed sampling of the market, the list is empty.

Paramètres

brandstringobligatoire
Brand id (br_…).
limitstring
starting_afterstring
Curseur : l'id du dernier objet de la page précédente.

Retour

Un dictionnaire dont la propriété data contient jusqu’à limit objets shelf_item, du plus récent au plus ancien, et has_more indique s’il reste une page. Lève une erreur en cas de problème.

curl


curl https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/shelf?limit=3 \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"

Node.js


const response = await fetch('https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/shelf?limit=3', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SKOUP_API_KEY}`,
  },
})
const data = await response.json()

PHP


$client = new GuzzleHttp\Client(['base_uri' => 'https://api.skoup.ai/v1/']);
$response = $client->request('GET', 'brands/br_034CyfRFSXUqzrbzV6MAfZ/shelf?limit=3', [
    'headers' => ['Authorization' => 'Bearer '.getenv('SKOUP_API_KEY')],
]);
$data = json_decode((string) $response->getBody(), true);

Python


import os, requests
 
response = requests.get(
    "https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/shelf?limit=3",
    headers={"Authorization": f"Bearer {os.environ['SKOUP_API_KEY']}"},
)
data = response.json()

Réponse


{
  "object": "list",
  "url": "/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/shelf",
  "has_more": false,
  "data": [
    {
      "object": "shelf_item",
      "id": "prod_5ZbXo1Z0hYV8sQnA3x1m2c",
      "kind": "product",
      "title": "Grizl CF SL 7",
      "category": "string",
      "image_url": "string",
      "price": "string",
      "currency": "EUR",
      "url": "https://hooks.example.com/skoup",
      "state": "error",
      "state_reason": {
        "kind": "alert",
        "model": "string",
        "alert_kind": "string",
        "element": "string",
        "label": "string",
        "count": 12
      },
      "share": 27.5,
      "delta": 27.5,
      "by_model": [
        {
          "model": "string",
          "runs": 12,
          "hits": 12,
          "position": 27.5
        }
      ],
      "trend": [
        {
          "week_starts_on": "2026-09-21",
          "by_model": [
            {
              "model": "string",
              "runs": 12,
              "hits": 12
            }
          ]
        }
      ],
      "prompt_count": 12,
      "leader": {
        "name": "Nordvelo",
        "brand_name": "string"
      },
      "perception_score": 12,
      "ai_revenue": {
        "amount": 27.5,
        "currency": "EUR",
        "orders": 12
      },
      "open_fixes": 12,
      "livemode": true
    }
  ]
}