Share links

Endpoints

POST/v1/brands/{brand}/share-links
GET/v1/brands/{brand}/share-links
DELETE/v1/brands/{brand}/share-links/{share_link}

Attributes

idstring
Unique identifier of the object (prefixed, opaque).
objectstring
share_link
brandstring
The brand the object belongs to (br_…).
kindenum
What a public link opens: a dated snapshot of the brand's visibility report (report, the apex page /r/{token}), or a live SVG badge to put on a site or a signature (badge, served by the API).
Possible values: report · badge
market_codestring
urlstring
A report: its public page. A badge: the page its image links to (the brand's active report, else skoup.ai).
badge_urlstringnullable
The SVG image — badges only.
embedstringnullable
The <a><img></a> to paste — badges only.
snapshot_atstringnullable
When the report was frozen — null for a badge, which is live.
expires_atstringnullable
revoked_atstringnullable
Set once revoked: the page and the badge answer 410.
viewsinteger
livemodeboolean
true for live data, false for the test-mode sandbox.
createdinteger
Time at which the object was created (unix timestamp, seconds).

The Share link object


{
  "id": "shl_034IhuucUGXrYD1T0nHfUT",
  "object": "share_link",
  "brand": "br_034CyfRFSXUqzrbzV6MAfZ",
  "kind": "report",
  "market_code": "string",
  "url": "https://hooks.example.com/skoup",
  "badge_url": "string",
  "embed": "string",
  "snapshot_at": "2026-09-21T02:40:00Z",
  "expires_at": "2026-09-21T02:40:00Z",
  "revoked_at": "2026-09-21T02:40:00Z",
  "views": 12,
  "livemode": true,
  "created": 1790000000
}

POST/v1/brands/{brand}/share-links

A report link freezes the brand’s visibility on market (default: the primary market) right now — never a live view, never a competitor or a query; parameter_invalid on market while nothing was measured there. A badge reads the share live, cached an hour. No expiry unless expires_at is given.

Parameters

brandstringrequired
Brand id (br_…).
kindenumrequired
What a public link opens: a dated snapshot of the brand's visibility report (report, the apex page /r/{token}), or a live SVG badge to put on a site or a signature (badge, served by the API).
Possible values: report · badge
marketstringnullable
Market code (ISO country, e.g. FR).
expires_atstringnullable

Returns

Returns the created share_link object. Raises an error if something goes wrong.

curl


curl -X POST https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/share-links \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{"kind":"report","market":"FR"}'

Node.js


const response = await fetch('https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/share-links', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SKOUP_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"kind":"report","market":"FR"}),
})
const data = await response.json()

PHP


$client = new GuzzleHttp\Client(['base_uri' => 'https://api.skoup.ai/v1/']);
$response = $client->request('POST', 'brands/br_034CyfRFSXUqzrbzV6MAfZ/share-links', [
    'headers' => ['Authorization' => 'Bearer '.getenv('SKOUP_API_KEY')],
    'json' => ['kind' => 'report', 'market' => 'FR'],
]);
$data = json_decode((string) $response->getBody(), true);

Python


import os, requests
 
response = requests.post(
    "https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/share-links",
    headers={"Authorization": f"Bearer {os.environ['SKOUP_API_KEY']}"},
    json={"kind": "report", "market": "FR"},
)
data = response.json()

Response


{
  "id": "shl_034IhuucUGXrYD1T0nHfUT",
  "object": "share_link",
  "brand": "br_034CyfRFSXUqzrbzV6MAfZ",
  "kind": "report",
  "market_code": "string",
  "url": "https://hooks.example.com/skoup",
  "badge_url": "string",
  "embed": "string",
  "snapshot_at": "2026-09-21T02:40:00Z",
  "expires_at": "2026-09-21T02:40:00Z",
  "revoked_at": "2026-09-21T02:40:00Z",
  "views": 12,
  "livemode": true,
  "created": 1790000000
}

GET/v1/brands/{brand}/share-links

The brand’s public links, active and revoked, newest first: a report is a dated snapshot anyone opens at its url without an account, a badge an SVG image (badge_url) with the HTML to paste (embed).

Parameters

brandstringrequired
Brand id (br_…).
limitinteger
Number of objects to return, between 1 and 100 (default 20).
starting_afterstring
Cursor: the id of the last object of the previous page.

Returns

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

curl


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

Node.js


const response = await fetch('https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/share-links?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/share-links?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/share-links?limit=3",
    headers={"Authorization": f"Bearer {os.environ['SKOUP_API_KEY']}"},
)
data = response.json()

Response


{
  "object": "list",
  "url": "/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/share-links",
  "has_more": false,
  "data": [
    {
      "id": "shl_034IhuucUGXrYD1T0nHfUT",
      "object": "share_link",
      "brand": "br_034CyfRFSXUqzrbzV6MAfZ",
      "kind": "report",
      "market_code": "string",
      "url": "https://hooks.example.com/skoup",
      "badge_url": "string",
      "embed": "string",
      "snapshot_at": "2026-09-21T02:40:00Z",
      "expires_at": "2026-09-21T02:40:00Z",
      "revoked_at": "2026-09-21T02:40:00Z",
      "views": 12,
      "livemode": true,
      "created": 1790000000
    }
  ]
}

DELETE/v1/brands/{brand}/share-links/{share_link}

Its page and its badge answer 410 from now on. The link stays listed with revoked_at set; revoking twice changes nothing.

Parameters

brandstringrequired
Brand id (br_…).
share_linkstringrequired
Share Link id (shl_…).

Returns

Returns an object with deleted: true. Raises an error if something goes wrong.

curl


curl -X DELETE https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/share-links/shl_034IhuucUGXrYD1T0nHfUT \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"

Node.js


const response = await fetch('https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/share-links/shl_034IhuucUGXrYD1T0nHfUT', {
  method: 'DELETE',
  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('DELETE', 'brands/br_034CyfRFSXUqzrbzV6MAfZ/share-links/shl_034IhuucUGXrYD1T0nHfUT', [
    'headers' => ['Authorization' => 'Bearer '.getenv('SKOUP_API_KEY')],
]);
$data = json_decode((string) $response->getBody(), true);

Python


import os, requests
 
response = requests.delete(
    "https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/share-links/shl_034IhuucUGXrYD1T0nHfUT",
    headers={"Authorization": f"Bearer {os.environ['SKOUP_API_KEY']}"},
)
data = response.json()

Response


{
  "id": "shl_034IhuucUGXrYD1T0nHfUT",
  "object": "share_link",
  "deleted": true
}

Share links

The Share link object

Attributes

Create a share link

Parameters

Returns

curl

Node.js

PHP

Python

List share links

Parameters

Returns

curl

Node.js

PHP

Python

Revoke a share link

Parameters

Returns

curl

Node.js

PHP

Python