Produits suivis

La liste shelf est l’écran d’accueil de l’app en API : chaque produit que Skoup suit pour une marque sur un marché — chaque établissement pour une marque locale, chaque offre pour un SaaS — avec la façon dont les assistants IA le traitent, déjà dans l’ordre où le regarder. Un seul appel répond à « lequel de mes produits a un problème dans les réponses des IA, et pourquoi ? ».

Une ligne n’est pas un enregistrement à part : son id est celui du produit (prod_…) ou de l’établissement (loc_…), à passer à GET /v1/brands/{brand}/products/{product} ou à la perception du produit. Elle n’écrit rien.

Suivi = un produit lié à au moins une requête du marché — cité dans une réponse, ou proche d’une requête par sa catégorie —, cité ou non. Un produit actif lié à aucune requête n’est pas dans la liste (l’app le montre « non suivi » dans le catalogue). Pendant l’essai, seule la sélection d’essai est suivie.

Je veux…

Je veux…	Appel
Les produits suivis d’un marché, dans l’ordre	`GET /v1/brands/{brand}/shelf?market=FR`
Seulement les produits sur lesquels une IA se trompe	`GET /v1/brands/{brand}/shelf?q=is:error`
Les produits qu’aucune réponse ne cite	`GET /v1/brands/{brand}/shelf?q=is:absent`
Les produits qui vendent par les IA	`GET /v1/brands/{brand}/shelf?q=has:revenue`
Là où un concurrent passe devant vous	`GET /v1/brands/{brand}/shelf?q=leader:"canyon"`
Ce qu’il y a à corriger sur un produit	`GET /v1/brands/{brand}/inbox?q=product:"Strade 7"`

Scope : metrics:read (c’est une mesure, pas le catalogue). Un assistant lit la même liste avec l’outil MCP get_shelf.

Les états

Skoup juge l’état de chaque ligne — le même juge que l’app, jamais une règle côté client. Dans l’ordre de la liste :

errorreinforcegoodabsentunmeasured

Pas un cycle de vie : une ligne change d'état à chaque sampling hebdomadaire et à chaque correctif.

`state`	Quand	`state_reason.kind`
`error`	Une alerte ouverte sur lui (prix faux, stock faux, caractéristique inventée, adresse / téléphone / horaires faux d’un établissement), ou un verdict de perception jugé faux (une caractéristique, le prix…)	`alert` (avec `alert_kind`) · `perception_false`
`absent`	Ses requêtes ont été posées sur la période, aucune réponse ne l’a cité	`never_cited` (`count` = ses requêtes)
`reinforce`	Cité, mais un différenciateur de sa fiche manque dans au moins la moitié des réponses jugées sur lui, ou son score de perception est sous 60	`usp_absent` (`label` = le différenciateur) · `weak_perception` (`count` = le score)
`unmeasured`	Aucune réponse sur ses requêtes sur la période, pour l’instant	`null`
`good`	Rien de tout cela	`null`

state_reason.model est l’IA qui l’a dit le plus souvent, element ce qui est en cause (price, availability, spec, attribute, address…).

Ordre

Les lignes arrivent triées : ce qu’une IA dit de faux, puis ce qui est à renforcer, puis les produits que les IA citent ; les jamais cités et les non mesurés viennent en dernier. Dans un même état : CA IA de la période, puis part de visibilité.

Recherche

q prend la grammaire de recherche de l’app :

Qualificatif	Valeurs
`is:`	`error`, `absent`, `reinforce`, `good`, `unmeasured`
`category:`	une partie de la catégorie (la ville d’un établissement), par ex. `category:"gravel"`
`model:`	cité au moins une fois par `chatgpt`, `claude`, `gemini`, `perplexity`…
`leader:`	une partie du nom ou de la marque du concurrent cité en premier
`has:`	`revenue` — un CA IA sur la période

- inverse un qualificatif (-is:good) ; le reste est du texte libre sur le titre ou le SKU.

Scénario : le point hebdo des produits en difficulté


curl -G "https://api.skoup.ai/v1/brands/br_034PJIMnN3EOTCU3TMUdLS/shelf" \
  --data-urlencode "market=FR" \
  --data-urlencode "q=is:error" \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"

À lancer après le sampling.completed de la semaine : chaque ligne dit ce qui ne va pas (state_reason) et quelle IA le dit.

Pièges

Pas d’event. La liste est calculée à l’appel. Suivez les objets derrière : sampling.completed pour la mesure, alert.created pour une erreur.
null n’est jamais 0. share vaut null pour une ligne jamais mesurée ; perception_score est null avant assez de réponses jugées ; ai_revenue est null sans commandes boutique (ou avant la première commande). Une fois les commandes reçues, un produit qui n’a rien vendu par une IA a amount: 0.
delta compare les deux derniers cycles hebdomadaires, share couvre toute la période : ce n’est pas la même fenêtre.
by_model ne liste que les modèles mesurés. Un modèle sans réponse sur les requêtes de la ligne est absent, jamais une ligne de zéros ; trend porte 12 semaines, la plus ancienne d’abord, un by_model vide pour une semaine sans sampling.
Avant le premier sampling terminé du marché, la liste est vide.
La pagination est un curseur dans l’ordre de la liste : limit (1–100, 20 par défaut) et starting_after = l’id de la dernière ligne de la page précédente. Un nouveau sampling réordonne la liste : repartez du début plutôt que de reprendre un vieux curseur.