Links API Reference¶
The /v1/links endpoints allow programmatic creation, lookup, listing, updating, deletion, and analytics retrieval for links.
1. Create Link¶
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"
}
2. List Links¶
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.
4. Get Link by Public ID¶
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.
5. Update Link¶
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.
6. Delete Link¶
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.
7. Get Link Analytics¶
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 }
]
}
}