Skip to Content
API referenceShelf

Shelf

Endpoints

The Shelf item object

Attributes

  • 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.

    Possible values: 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 <br/> « Une IA se trompe »: an open alert on it, or a false verdict of its perception. | | absent <br/> « Absent »: its queries were asked, no answer named it. | | reinforce <br/> « À renforcer »: cited, but a differentiator does not come through or its perception is weak. | | good <br/> « Bien cité ». | | unmeasured <br/> « Pas encore mesuré »: no answer on its queries over the period. |

    Possible values: error · absent · reinforce · good · unmeasured

  • state_reasonobject
    Show child attributes
    • 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 <br/> An open alert on the product / establishment (price, stock, invented spec, local fact). | | perception_false <br/> A perception gap judged false (a spec, the price…) not carried by an alert. | | never_cited <br/> Its queries were asked, no answer named it. | | usp_absent <br/> A differentiator of its sheet missing from too many of the answers. | | weak_perception <br/> Its perception score is under the threshold. |

      Possible values: 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
    Show child attributes
    • modelstring
    • runsinteger
    • hitsinteger
    • positionnumbernullable
  • trendarray of object
    Show child attributes
    • week_starts_onstring
    • by_modelarray of object
      Show child attributes
      • modelstring
      • runsinteger
      • hitsinteger
  • prompt_countinteger
  • leaderobjectnullable

    The competitor recommended first most often on its queries.

    Show child attributes
    • namestring
    • brand_namestring
  • perception_scoreintegernullable

    Conforming ÷ verdicts, 0–100; null before enough judged answers.

  • ai_revenueobjectnullable

    null without store orders.

    Show child attributes
    • amountnumber
    • currencystring
    • ordersinteger
  • open_fixesinteger

    Its open lines in the inbox.

  • livemodeboolean

    true for live data, false for the test-mode sandbox.

The Shelf item object
{
  "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.

Parameters

  • brandstringrequired

    Brand id (br_…).

  • limitstring
  • starting_afterstring

    Cursor: the id of the last object of the previous page.

Returns

A dictionary with a data property holding up to limit shelf_item objects, newest first, and has_more telling whether another page exists. Raises an error if something goes wrong.

curl https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/shelf?limit=3 \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"
Response
{
  "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
    }
  ]
}
Last updated on
Share linksTasks