Liens de partage

Un lien de partage montre la visibilité IA d’une marque à quelqu’un qui n’a pas de compte Skoup : le client d’une agence, un comité, un partenaire. Deux sortes :

un lien rapport ouvre une page (https://app.skoup.ai/r/…) qui montre un instantané de la visibilité de la marque sur un marché — la part des réponses IA qui la citent avec son intervalle de confiance, sa position moyenne, la part par IA, douze semaines de tendance et le score readiness — figé à la création du lien. Jamais une vue vivante, jamais un concurrent nommé ni une requête. Pour une agence dont les rapports sont en marque blanche, la page porte le nom, la couleur et le logo de l’agence.
un lien badge est une image SVG (badge_url) « Visibilité IA · 42 % · Skoup », vivante : la part de la marque sur le marché au dernier sampling complet, mise en cache une heure. Tant que rien n’est mesuré, elle dit « mesure en cours », jamais 0. embed est le HTML à coller sur un site ou dans une signature ; l’image pointe vers la page du rapport actif de la marque s’il en existe un, sinon vers skoup.ai.

Un lien est révocable et expire si on le demande. Ses URLs portent le secret : qui les a ouvre la page.

Cycle de vie d’un lien

activerevoked

un lien dont expires_at est passé est fermé aussi. Les deux répondent 410 à qui les ouvre ; le lien reste listé avec son nombre de vues.

Je veux…

Je veux…	Appel
Envoyer à un client un rapport daté de sa marque	`POST /v1/brands/{brand}/share-links` avec `kind: "report"` et `market` (défaut : le marché principal)
Poser un badge de visibilité vivant sur un site	`POST /v1/brands/{brand}/share-links` avec `kind: "badge"`, puis coller `embed`
Lister ce que la marque a partagé et combien de fois chaque page a été ouverte	`GET /v1/brands/{brand}/share-links` (`views`)
Fermer une page ou un badge	`DELETE /v1/brands/{brand}/share-links/{share_link}`
Partager un rapport plus frais	Créer un nouveau lien `report` : un instantané ne bouge jamais

Scopes : brands:read pour lister, sharing:write pour créer et révoquer. Events : aucun — un lien est créé par qui le demande ; relisez la liste.

Scénario : une page de rapport mensuelle pour un client


curl -X POST "https://api.skoup.ai/v1/brands/br_034PJIMnN3EOTCU3TMUdLS/share-links" \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{"kind": "report", "market": "FR", "expires_at": "2026-12-31T23:59:59Z"}'


{
  "id": "shl_5kQ2mN8pR4tV7xZ1bC3dF6",
  "object": "share_link",
  "brand": "br_034PJIMnN3EOTCU3TMUdLS",
  "kind": "report",
  "market_code": "FR",
  "url": "https://app.skoup.ai/r/a1B2c3…",
  "badge_url": null,
  "embed": null,
  "snapshot_at": "2026-10-07T09:12:44Z",
  "expires_at": "2026-12-31T23:59:59Z",
  "revoked_at": null,
  "views": 0,
  "livemode": false,
  "created": 1791011564
}

Lancez-le après chaque sampling.completed de fin de mois et envoyez l’url au client : la page montrera le mois tel qu’il a été mesuré, quoi qu’il arrive ensuite.

Pièges

Un lien rapport est un instantané. Il montre ce qui était mesuré à sa création — snapshot_at — pas les chiffres du moment. Pour partager un état plus récent, créez un autre lien.
parameter_invalid sur market tant que le marché n’a aucun sampling complet : il n’y a rien à figer. Un badge peut être créé avant la première mesure ; il dit « mesure en cours » jusque-là.
L’URL est le secret. Qui l’a ouvre la page ; révoquez le lien plutôt que d’espérer qu’il soit oublié. Un lien révoqué ne se rouvre pas.
Les badges sont en cache une heure chez Skoup et dans les navigateurs (Cache-Control: public, max-age=3600) : un changement de part apparaît dans l’heure ; une révocation peut prendre autant sur une page déjà ouverte.
?lang=en sur badge_url rend le badge en anglais (défaut : français). embed prend déjà la langue de l’espace de la clé.