Skip to content

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.


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"
}

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.


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.


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.


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).


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"
    }
  ]
}

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 with status: "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."
}

Response 202 Accepted (Export Processing)

{
  "status": "processing",
  "download_url": null,
  "expires_in": null,
  "message": "Export initiated. Check back shortly."
}