Links API

Use the Links API to create tracking links, manage slugs, and review click performance.

🌐 Endpoints

GET/api/links

List tracking links for a site and return aggregate link stats.

🔑 Authentication required: Yes, via session cookie.

Parameters

Name	Type	Required	Description
siteId	number	No	Site to query. If omitted, Ghost ID resolves the first accessible site.

Example Request

Bash

curl --request GET \
  --url "https://analytics.ghostid.ai/api/links?siteId=4" \
  --cookie "session=YOUR_SESSION_COOKIE"

Response Example

JSON

{
  "links": [
    {
      "id": "lnk_4s9x2m1k0q",
      "site_id": 4,
      "slug": "spring-launch",
      "destination_url": "https://example.com/pricing",
      "campaign": "spring-2026",
      "source": "newsletter",
      "medium": "email",
      "content": "hero-button",
      "notes": "Main launch CTA",
      "is_active": true,
      "total_clicks": 128,
      "clicks_today": 9,
      "last_clicked_at": "2026-03-10T16:58:00.000Z"
    }
  ],
  "siteSlug": "ghostid",
  "stats": {
    "totalLinks": 12,
    "totalClicks": 621,
    "clicksToday": 33,
    "topSource": "newsletter"
  }
}

POST/api/links

Create a new tracking link for a site.

🔑 Authentication required: Yes, via session cookie.

Parameters

Name	Type	Required	Description
siteId	number	Yes	Site that owns the link.
destinationUrl	string	Yes	Destination URL visitors should land on.
slug	string	No	Preferred slug. Ghost ID generates one if omitted.
campaign	string	No	Campaign label used for attribution.
source	string	No	Traffic source value.
medium	string	No	Traffic medium value.
content	string	No	Content or creative variation.
notes	string	No	Internal notes for the link.
link_type	string	No	One of content, ad, or bio. Defaults to content.

Request Body

JSON

{
  "siteId": 4,
  "destinationUrl": "https://example.com/pricing",
  "slug": "spring-launch",
  "campaign": "spring-2026",
  "source": "newsletter",
  "medium": "email",
  "content": "hero-button",
  "notes": "Main launch CTA",
  "link_type": "content"
}

Example Request

Bash

curl --request POST \
  --url https://analytics.ghostid.ai/api/links \
  --cookie "session=YOUR_SESSION_COOKIE" \
  --header "Content-Type: application/json" \
  --data '{
    "siteId": 4,
    "destinationUrl": "https://example.com/pricing",
    "slug": "spring-launch",
    "campaign": "spring-2026",
    "source": "newsletter",
    "medium": "email"
  }'

Response Example

JSON

{
  "link": {
    "id": "lnk_4s9x2m1k0q",
    "site_id": 4,
    "slug": "spring-launch",
    "destination_url": "https://example.com/pricing",
    "campaign": "spring-2026",
    "source": "newsletter",
    "medium": "email",
    "content": "",
    "notes": "",
    "is_active": true,
    "link_type": "content"
  },
  "fullUrl": "https://ghst.id/l/ghostid/spring-launch"
}

PUT/api/links/:id

Update an existing tracking link.

🔑 Authentication required: Yes, via session cookie.

Parameters

Name	Type	Required	Description
id	path	Yes	Tracking link ID.
destinationUrl	string	No	Updated destination URL.
slug	string	No	Updated slug.
campaign	string	No	Updated campaign value.
source	string	No	Updated source value.
medium	string	No	Updated medium value.
content	string	No	Updated content value.
notes	string	No	Updated internal notes.
is_active	boolean	No	Enable or disable the link.
expires_at	string	No	Optional ISO timestamp when the link expires.
max_clicks	number	No	Optional max click threshold.
tags	array	No	Optional JSON array of tags.

Request Body

JSON

{
  "campaign": "spring-2026-retargeting",
  "is_active": true,
  "notes": "Retargeting variant",
  "tags": ["retargeting", "paid-social"]
}

Example Request

Bash

curl --request PUT \
  --url https://analytics.ghostid.ai/api/links/lnk_4s9x2m1k0q \
  --cookie "session=YOUR_SESSION_COOKIE" \
  --header "Content-Type: application/json" \
  --data '{
    "campaign": "spring-2026-retargeting",
    "notes": "Retargeting variant",
    "tags": ["retargeting", "paid-social"]
  }'

Response Example

JSON

{
  "link": {
    "id": "lnk_4s9x2m1k0q",
    "slug": "spring-launch",
    "campaign": "spring-2026-retargeting",
    "notes": "Retargeting variant",
    "is_active": true,
    "tags": ["retargeting", "paid-social"]
  }
}

DELETE/api/links/:id

Delete a tracking link.

🔑 Authentication required: Yes, via session cookie.

Parameters

Name	Type	Required	Description
id	path	Yes	Tracking link ID to remove.

Example Request

Bash

curl --request DELETE \
  --url https://analytics.ghostid.ai/api/links/lnk_4s9x2m1k0q \
  --cookie "session=YOUR_SESSION_COOKIE"

Response Example

JSON

{
  "success": true
}

GET/api/links/check-slug

Check whether a link slug is available for a site.

🔑 Authentication required: Yes, via session cookie.

Parameters

Name	Type	Required	Description
slug	string	Yes	Slug to validate.
siteId	number	No	Site to validate against. Defaults to the active site.

Example Request

Bash

curl --request GET \
  --url "https://analytics.ghostid.ai/api/links/check-slug?slug=spring-launch&siteId=4" \
  --cookie "session=YOUR_SESSION_COOKIE"

Response Example

JSON

{
  "available": true,
  "slug": "spring-launch"
}

GET/api/link-analytics

Return click-level analytics with breakdowns by country, city, campaign, source, and day.

🔑 Authentication required: Yes, via session cookie.

Parameters

Name	Type	Required	Description
siteId	number	No	Site to query. If omitted, Ghost ID resolves the first accessible site.
range	string	No	One of 7d, 30d, 90d, or all. Defaults to 7d.
slug	string	No	Filter analytics to a specific slug.
campaign	string	No	Filter analytics to a campaign.
source	string	No	Filter analytics to a source.

Example Request

Bash

curl --request GET \
  --url "https://analytics.ghostid.ai/api/link-analytics?siteId=4&range=30d&campaign=spring-2026" \
  --cookie "session=YOUR_SESSION_COOKIE"

Response Example

JSON

{
  "clicks": [
    {
      "id": "91",
      "ghost_vid": "gv_a1b2c3d4_e5f6g7h8",
      "slug": "spring-launch",
      "campaign": "spring-2026",
      "source": "newsletter",
      "country": "United States",
      "city": "Austin",
      "lat": 30.2672,
      "lon": -97.7431,
      "device_type": "desktop",
      "browser": "Chrome",
      "created_at": "2026-03-10T17:13:51.000Z"
    }
  ],
  "byCountry": [
    { "country": "United States", "clicks": 88 }
  ],
  "byCity": [
    { "city": "Austin", "country": "United States", "clicks": 15, "lat": 30.2672, "lon": -97.7431 }
  ],
  "byCampaign": [
    { "campaign": "spring-2026", "clicks": 102 }
  ],
  "bySource": [
    { "source": "newsletter", "clicks": 77 }
  ],
  "byDay": [
    { "date": "2026-03-10", "clicks": 14 }
  ],
  "total": 102
}

Events & Tracking

Revenue