Skip to content

Links API Reference

The /v1/links endpoints allow programmatic creation, lookup, listing, updating, deletion, and analytics retrieval for links.


POST /v1/links

Creates a new link under your authenticated organization.

Required Permissions

  • Authentication: Bearer Token or HMAC-SHA256 signature
  • Required Scope: links:write

Request Body

Parameter Type Required Description
destination_url string Yes Destination URL to redirect to. Must include valid scheme (https://, http://).
domain string Yes Short domain (e.g. rby.one or verified custom branded domain).
title string | null No Optional human-readable title (up to 255 chars).
group_public_id string | null No Public ID of an existing campaign group (e.g. grp_01J8K92M4).
custom_alias string | null No Custom short code (3–64 alphanumeric characters, hyphens, or underscores). Only allowed on verified custom domains.
ios_url string | null No Deep-link or App Store destination for iOS devices (Pro or higher).
android_url string | null No Deep-link or Play Store destination for Android devices (Pro or higher).
fallback_url string | null No Fallback URL if link has expired.
utm_source string | null No Google Analytics campaign source (e.g. newsletter).
utm_medium string | null No Google Analytics campaign medium (e.g. email).
utm_campaign string | null No Google Analytics campaign name (e.g. summer_sale).
utm_term string | null No Google Analytics campaign term.
utm_content string | null No Google Analytics campaign content.
forward_parameters boolean No Forward incoming query parameters to the destination URL. Defaults to true.
og_title string | null No Custom OpenGraph title for social crawler previews (Pro or higher).
og_description string | null No Custom OpenGraph description (Pro or higher).
og_image string | null No Custom OpenGraph image URL (Pro or higher).
geo_routing object | null No Key-value mapping of 2-letter ISO country codes to country-specific URLs (Pro or higher).
password string | null No Password protecting the short link (Pro or higher).
expires_at string | null No ISO 8601 UTC timestamp when the link should expire (Pro or higher).

Default Domain Note

On the default platform domain (rby.one), custom aliases are not permitted. Leave custom_alias omitted to receive an auto-generated 8-character short code (e.g. https://rby.one/A7K92X1P). Custom aliases may only be assigned on verified custom branded domains.

Example Request Body

{
  "destination_url": "https://example.com/promotion",
  "domain": "rby.one",
  "title": "Summer Campaign Link",
  "group_public_id": "grp_01J8K92M4",
  "ios_url": "https://apps.apple.com/app/id123456",
  "android_url": "https://play.google.com/store/apps/details?id=com.example",
  "fallback_url": "https://example.com/expired",
  "utm_source": "newsletter",
  "utm_medium": "email",
  "utm_campaign": "summer_sale",
  "forward_parameters": true,
  "og_title": "Summer Promotion",
  "og_description": "Get 20% off all orders this week.",
  "og_image": "https://example.com/images/banner.png",
  "expires_at": "2026-12-31T23:59:59Z"
}

Response 201 Created

{
  "public_id": "lnk_01J8K92M4",
  "short_code": "A7K92X1P",
  "domain": "rby.one",
  "short_url": "https://rby.one/A7K92X1P",
  "destination_url": "https://example.com/promotion",
  "title": "Summer Campaign Link",
  "group_public_id": "grp_01J8K92M4",
  "custom_alias": false,
  "is_active": true,
  "ios_url": "https://apps.apple.com/app/id123456",
  "android_url": "https://play.google.com/store/apps/details?id=com.example",
  "fallback_url": "https://example.com/expired",
  "utm_source": "newsletter",
  "utm_medium": "email",
  "utm_campaign": "summer_sale",
  "utm_term": null,
  "utm_content": null,
  "forward_parameters": true,
  "og_title": "Summer Promotion",
  "og_description": "Get 20% off all orders this week.",
  "og_image": "https://example.com/images/banner.png",
  "geo_routing": null,
  "has_password": false,
  "expires_at": "2026-12-31T23:59:59",
  "created_at": "2026-11-07T21:00:00",
  "updated_at": "2026-11-07T21:00:00"
}

GET /v1/links

Lists links belonging to the authenticated organization using cursor-based pagination. Results are ordered newest first.

Required Permissions

  • Authentication: Bearer Token or HMAC-SHA256 signature
  • Required Scope: links:read

Query Parameters

Parameter Type Default Description
limit integer 100 Maximum results to return per page (min: 1, max: 100).
cursor string | null null Pagination cursor returned in meta.next_cursor from the previous page.
domain string | null null Filter links by domain (e.g. rby.one).
group_public_id string | null null Filter by campaign group public ID. Pass "none" to query ungrouped links.
is_active boolean | null null Filter active (true) or deactivated (false) links.
search string | null null Substring search across title, short_code, and destination_url.

Response 200 OK

{
  "data": [
    {
      "public_id": "lnk_01J8K92M4",
      "short_code": "A7K92X1P",
      "domain": "rby.one",
      "short_url": "https://rby.one/A7K92X1P",
      "destination_url": "https://example.com/promotion",
      "title": "Summer Campaign Link",
      "group_public_id": "grp_01J8K92M4",
      "custom_alias": false,
      "is_active": true,
      "ios_url": "https://apps.apple.com/app/id123456",
      "android_url": "https://play.google.com/store/apps/details?id=com.example",
      "fallback_url": "https://example.com/expired",
      "utm_source": "newsletter",
      "utm_medium": "email",
      "utm_campaign": "summer_sale",
      "utm_term": null,
      "utm_content": null,
      "forward_parameters": true,
      "og_title": "Summer Promotion",
      "og_description": "Get 20% off all orders this week.",
      "og_image": "https://example.com/images/banner.png",
      "geo_routing": null,
      "has_password": false,
      "expires_at": "2026-12-31T23:59:59",
      "created_at": "2026-11-07T21:00:00",
      "updated_at": "2026-11-07T21:00:00"
    }
  ],
  "meta": {
    "next_cursor": "E-ABA...",
    "has_more": true,
    "count": null
  }
}

3. Reverse Lookup by Domain and Short Code

GET /v1/links/lookup?domain={domain}&short_code={short_code}

Retrieves short link details using its domain and short code combination.

Required Permissions

  • Authentication: Bearer Token or HMAC-SHA256 signature
  • Required Scope: links:read

Query Parameters

Parameter Type Required Description
domain string Yes Short domain name (e.g. rby.one).
short_code string Yes Short code or custom slug (e.g. A7K92X1P).

Response 200 OK

Returns the LinkApiResponse schema.


GET /v1/links/{public_id}

Retrieves complete metadata and configuration for a short link by its unique public ID.

Required Permissions

  • Authentication: Bearer Token or HMAC-SHA256 signature
  • Required Scope: links:read

Path Parameters

  • public_id (string, required): The short link public ID (e.g. lnk_01J8K92M4).

Response 200 OK

Returns the LinkApiResponse schema.


PUT /v1/links/{public_id}

Updates destination URL, targeting rules, password protection, OpenGraph previews, or active status.

Required Permissions

  • Authentication: Bearer Token or HMAC-SHA256 signature
  • Required Scope: links:write

Request Body

All fields are optional. Only fields included in the JSON payload are updated.

{
  "destination_url": "https://example.com/new-promotion",
  "title": "Updated Summer Campaign Title",
  "is_active": true,
  "ios_url": "https://apps.apple.com/app/id654321",
  "android_url": "https://play.google.com/store/apps/details?id=com.newexample",
  "fallback_url": "https://example.com/expired-new",
  "utm_source": "summer_newsletter",
  "utm_medium": "email",
  "utm_campaign": "summer_clearance",
  "forward_parameters": true,
  "og_title": "Clearance Sale",
  "og_description": "Final days: up to 50% off.",
  "og_image": "https://example.com/images/clearance.png",
  "expires_at": "2026-08-31T23:59:59Z"
}

Response 200 OK

Returns the updated LinkApiResponse schema.


DELETE /v1/links/{public_id}

Deactivates (soft delete) or permanently purges (hard delete) a link.

Required Permissions

  • Authentication: Bearer Token or HMAC-SHA256 signature
  • Required Scope: links:write

Query Parameters

Parameter Type Default Description
hard boolean false If false (default), soft-deactivates the link (is_active = false). Redirections stop immediately, but analytics are retained. If true, permanently purges the entity from storage.

Response 204 No Content

No response body is returned upon successful deactivation or deletion.


GET /v1/links/{public_id}/stats

Retrieves aggregated clickstream metrics, time-series distributions, and categorical breakdowns (devices, browsers, operating systems, countries, referrers) for the short link.

Required Permissions

  • Authentication: Bearer Token or HMAC-SHA256 signature
  • Required Scope: analytics:read

Query Parameters

Parameter Type Default Description
period integer | string 30 Timeframe in days. Supported values: 7, 30, 60, 90, 180, 365, 730, 1825. Maximum range is validated against your plan's analytics retention limit.

Response 200 OK

{
  "total_clicks": 1420,
  "unique_visitors": 1180,
  "bot_clicks": 34,
  "period": "30d",
  "interval": "day",
  "start_date": "2026-10-08",
  "end_date": "2026-11-07",
  "time_series": [
    {
      "date": "2026-10-08",
      "clicks": 45,
      "unique_visitors": 38
    },
    {
      "date": "2026-10-09",
      "clicks": 62,
      "unique_visitors": 55
    }
  ],
  "breakdowns": {
    "devices": [
      { "name": "Mobile", "count": 890, "percentage": 62.68 },
      { "name": "Desktop", "count": 480, "percentage": 33.80 },
      { "name": "Tablet", "count": 50, "percentage": 3.52 }
    ],
    "browsers": [
      { "name": "Chrome", "count": 780, "percentage": 54.93 },
      { "name": "Safari", "count": 510, "percentage": 35.92 },
      { "name": "Firefox", "count": 130, "percentage": 9.15 }
    ],
    "os": [
      { "name": "iOS", "count": 640, "percentage": 45.07 },
      { "name": "Android", "count": 350, "percentage": 24.65 },
      { "name": "macOS", "count": 270, "percentage": 19.01 },
      { "name": "Windows", "count": 160, "percentage": 11.27 }
    ],
    "countries": [
      { "name": "United States", "count": 620, "percentage": 43.66 },
      { "name": "United Kingdom", "count": 240, "percentage": 16.90 },
      { "name": "Germany", "count": 180, "percentage": 12.68 },
      { "name": "Greece", "count": 150, "percentage": 10.56 }
    ],
    "referrers": [
      { "name": "Direct", "count": 610, "percentage": 42.96 },
      { "name": "google.com", "count": 410, "percentage": 28.87 },
      { "name": "t.co", "count": 260, "percentage": 18.31 },
      { "name": "linkedin.com", "count": 140, "percentage": 9.86 }
    ]
  }
}