Share links

A share link lets someone without a Skoup account see a brand’s AI visibility: a client of an agency, a board, a partner. Two kinds:

a report link opens a page (https://app.skoup.ai/r/…) showing a snapshot of the brand’s visibility on one market — the share of AI answers citing it with its confidence interval, its mean position, the share per AI model, twelve weeks of trend and the readiness score — frozen when the link is created. It is never a live view, and it never names a competitor or a query. For an agency whose reports are white-labelled, the page carries the agency’s name, colour and logo.
a badge link is an SVG image (badge_url) reading « AI visibility · 42 % · Skoup », live: the brand’s share on the market at its last full sampling, cached for an hour. While nothing was measured it reads « measuring », never 0. embed is the HTML to paste on a site or in a signature; the image links to the brand’s active report page when one exists, else to skoup.ai.

A link is revocable and optionally expires. Its URLs carry the secret: whoever has them opens the page.

Lifecycle of a link

activerevoked

a link with an expires_at in the past is closed too. Both answer 410 to whoever opens them; the link stays listed with its view count.

I want to…

I want to…	Call
Send a client a dated report of their brand	`POST /v1/brands/{brand}/share-links` with `kind: "report"` and `market` (default: the primary market)
Put a live visibility badge on a site	`POST /v1/brands/{brand}/share-links` with `kind: "badge"`, then paste `embed`
List what the brand has shared and how many times each page was opened	`GET /v1/brands/{brand}/share-links` (`views`)
Close a page or a badge	`DELETE /v1/brands/{brand}/share-links/{share_link}`
Share a fresher report	Create a new `report` link: a snapshot never moves

Scopes: brands:read to list, sharing:write to create and revoke. Events: none — a link is created by whoever asks for it; read the list.

Scenario: a monthly report page for a 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
}

Run it after each monthly sampling.completed and mail the url to the client: the page will show the month as it was measured, whatever happens next.

Pitfalls

A report link is a snapshot. It shows what was measured when it was created — snapshot_at — not the current figures. To share a newer state, create another link.
parameter_invalid on market while the market has no completed sampling: there is nothing to freeze. A badge can be created before the first measure; it says « measuring » until then.
The URL is the secret. Anyone with it opens the page; revoke the link rather than hoping it is forgotten. A revoked link cannot be reopened.
Badges are cached an hour by Skoup and by browsers (Cache-Control: public, max-age=3600): a change of share shows within the hour; a revocation can take as long on a page already opened.
?lang=en on badge_url renders the badge in English (default: French). embed already picks the language of the key’s workspace.