Link Groups API Reference¶
The /v1/groups endpoints allow organizing short links into structured link groups, managing bulk link batches, retrieving aggregated group analytics, and generating CSV exports.
1. Create Link Group¶
POST /v1/groups
Creates a new link group for the authenticated organization.
Required Permissions¶
- Authentication: Bearer Token or HMAC-SHA256 signature
- Required Scope:
groups:write
Request Body¶
| Parameter | Type | Required | Description |
|---|---|---|---|
title |
string |
Yes | Link group title (1 to 128 characters). |
description |
string | null |
No | Optional description (up to 1,000 characters). |
{
"title": "Summer Catalog 2026",
"description": "Cross-channel promotional links for summer collection"
}
Response 201 Created¶
{
"public_id": "grp_01J8K92M4",
"title": "Summer Catalog 2026",
"description": "Cross-channel promotional links for summer collection",
"link_count": 0,
"is_frozen": false,
"status": "active",
"created_at": "2026-11-07T21:00:00",
"updated_at": "2026-11-07T21:00:00"
}
2. List Link Groups¶
GET /v1/groups
Returns a paginated list of all link groups in the authenticated organization.
Required Permissions¶
- Authentication: Bearer Token or HMAC-SHA256 signature
- Required Scope:
groups: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. |
include_inactive |
boolean |
false |
If true, includes deactivated / soft-deleted groups. |
search |
string | null |
null |
Case-insensitive title search filter. |
Response 200 OK¶
{
"data": [
{
"public_id": "grp_01J8K92M4",
"title": "Summer Catalog 2026",
"description": "Cross-channel promotional links for summer collection",
"link_count": 45,
"is_frozen": false,
"status": "active",
"created_at": "2026-11-01T10:00:00",
"updated_at": "2026-11-01T10:00:00"
}
],
"meta": {
"next_cursor": null,
"has_more": false,
"count": null
}
}
3. Get Group by Public ID¶
GET /v1/groups/{public_id}
Retrieves link group metadata and live link counter.
Required Permissions¶
- Authentication: Bearer Token or HMAC-SHA256 signature
- Required Scope:
groups:read
Path Parameters¶
public_id(string, required): Link group public ID (e.g.grp_01J8K92M4).
Response 200 OK¶
Returns the GroupApiResponse schema.
4. Update Link Group¶
PUT /v1/groups/{public_id}
Updates group title and description.
Required Permissions¶
- Authentication: Bearer Token or HMAC-SHA256 signature
- Required Scope:
groups:write
Request Body¶
{
"title": "Summer Catalog 2026 (Updated)",
"description": "Updated description for summer collection"
}
Response 200 OK¶
Returns the updated GroupApiResponse schema.
5. Delete Link Group¶
DELETE /v1/groups/{public_id}
Deactivates (soft delete) or permanently purges (hard delete) a link group and all associated short links.
Required Permissions¶
- Authentication: Bearer Token or HMAC-SHA256 signature
- Required Scope:
groups:write
Query Parameters¶
| Parameter | Type | Default | Description |
|---|---|---|---|
hard |
boolean |
false |
If false (default), marks group inactive and immediately stops redirections for all links in the group. If true, schedules permanent background purge. |
Response 204 No Content¶
No response body is returned upon successful deactivation or deletion.
6. List Links in Group¶
GET /v1/groups/{public_id}/links
Lists all short links belonging to the specified campaign group using cursor pagination.
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. |
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 Collection Link",
"group_public_id": "grp_01J8K92M4",
"custom_alias": false,
"is_active": true,
"created_at": "2026-11-07T21:00:00"
}
],
"meta": {
"next_cursor": null,
"has_more": false,
"count": null
}
}
7. Group Aggregate Analytics¶
GET /v1/groups/{public_id}/stats
Retrieves consolidated clickstream metrics, time-series distributions, and categorical breakdowns aggregated across all links in the group.
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. Validated against your plan's analytics retention limit. |
Response 200 OK¶
Returns the AnalyticsStatsResponseSchema (matching the structure documented in Links API Analytics).
8. Bulk Batch Link Creation¶
POST /v1/groups/{public_id}/links/batch
Creates up to 500 links in a single atomic batch under the specified link group. All links in the batch share the specified domain.
Required Permissions¶
- Authentication: Bearer Token or HMAC-SHA256 signature
- Required Scope:
links:write
Request Body¶
| Parameter | Type | Required | Description |
|---|---|---|---|
domain |
string |
Yes | Target short domain for all links in this batch (e.g. rby.one). |
links |
array |
Yes | Array of link objects to generate (1 to 500 items). |
links[].destination_url |
string |
Yes | Target URL for this specific link. |
links[].title |
string | null |
No | Optional link title. |
links[].ios_url |
string | null |
No | Deep-link destination for iOS devices. |
links[].android_url |
string | null |
No | Deep-link destination for Android devices. |
links[].utm_source |
string | null |
No | UTM source parameter. |
links[].utm_medium |
string | null |
No | UTM medium parameter. |
links[].utm_campaign |
string | null |
No | UTM campaign parameter. |
Example Request Body¶
{
"domain": "rby.one",
"links": [
{
"destination_url": "https://example.com/promo-shoes",
"title": "Summer Shoes Promo",
"utm_source": "newsletter",
"utm_medium": "email",
"utm_campaign": "summer_shoes"
},
{
"destination_url": "https://example.com/promo-bags",
"title": "Summer Bags Promo",
"utm_source": "newsletter",
"utm_medium": "email",
"utm_campaign": "summer_bags"
}
]
}
Response 201 Created¶
{
"group_public_id": "grp_01J8K92M4",
"total_created": 2,
"links": [
{
"public_id": "lnk_01J8K92M4A",
"short_code": "A7K92X1P",
"domain": "rby.one",
"short_url": "https://rby.one/A7K92X1P",
"destination_url": "https://example.com/promo-shoes",
"title": "Summer Shoes Promo",
"group_public_id": "grp_01J8K92M4",
"is_active": true,
"created_at": "2026-11-07T21:00:00"
},
{
"public_id": "lnk_01J8K92M4B",
"short_code": "B8L03Y2Q",
"domain": "rby.one",
"short_url": "https://rby.one/B8L03Y2Q",
"destination_url": "https://example.com/promo-bags",
"title": "Summer Bags Promo",
"group_public_id": "grp_01J8K92M4",
"is_active": true,
"created_at": "2026-11-07T21:00:00"
}
]
}
9. Export Group Links (CSV)¶
GET /v1/groups/{public_id}/export
Generates a secure, time-limited signed URL to download a CSV containing all short links in the group (destination_url, short_url, short_code, title).
- For groups with up to 2,000 links, the export is generated synchronously. If a dynamic group contains no links yet (
link_count: 0), a CSV containing only the standard header row (destination_url,short_url,short_code,title) is generated immediately and returned withstatus: "ready". - For groups with more than 2,000 links, generation runs asynchronously in the background. If the file is still preparing, the endpoint returns
202 Accepted.
Required Permissions¶
- Authentication: Bearer Token or HMAC-SHA256 signature
- Required Scope:
groups:read
Query Parameters¶
| Parameter | Type | Default | Description |
|---|---|---|---|
refresh |
boolean |
false |
If true, forces regeneration of the export CSV file. |
Response 200 OK (Export Ready)¶
{
"status": "ready",
"download_url": "https://storage.googleapis.com/ruby-exports/link_groups/org_123/group_456_export.csv?GoogleAccessId=...",
"expires_in": 3600,
"message": "Export is ready for download."
}