Links API

Create, retrieve, update, and delete short links. The Links API supports custom slugs, custom domains, UTM parameters, device targeting, password protection, expiration, and tags.

The link object

A link represents a short URL that redirects to a destination. Links belong to a workspace and can be tagged, password-protected, and configured with UTM parameters and device-specific targets.

Field	Type	Description
id	string	Unique link identifier (e.g. `lnk_abc123`)
url	string	The destination URL
short_url	string	The full short URL including domain
slug	string	The slug portion of the short URL
domain	string	The domain used for the short link
title	string \| null	Optional title for the link
tags	string[]	Array of tag strings
clicks	number	Total click count
utm_source	string \| null	UTM source parameter
utm_medium	string \| null	UTM medium parameter
utm_campaign	string \| null	UTM campaign parameter
expires_at	string \| null	ISO 8601 expiration timestamp
password	string \| null	Password protection (write-only, never returned in responses)
ios_target	string \| null	iOS-specific redirect URL
android_target	string \| null	Android-specific redirect URL
created_at	string	ISO 8601 creation timestamp
updated_at	string	ISO 8601 last update timestamp

List links

Retrieve a paginated list of links in the workspace. Supports filtering by tag, domain, search query, and date range.

GET/api/v1/links

Query parameters

Parameter	Type	Default	Description
limit	integer	25	Number of items per page (max: 100)
cursor	string	—	Cursor from a previous response for pagination
search	string	—	Search links by URL, slug, or title
tag	string	—	Filter by tag name
domain	string	—	Filter by domain
sort	string	created_at	Sort field: `created_at`, `clicks`, `updated_at`
order	string	desc	Sort order: `asc` or `desc`

Request

curl "https://mask.pk/api/v1/links?limit=10&tag=campaign-q1" \
  -H "Authorization: Bearer mk_live_abc123def456"

Response

{
  "data": [
    {
      "id": "lnk_abc123",
      "url": "https://example.com/my-page",
      "short_url": "https://go.yourbrand.com/my-link",
      "slug": "my-link",
      "domain": "go.yourbrand.com",
      "title": "My Campaign Link",
      "tags": ["campaign-q1", "social"],
      "clicks": 142,
      "utm_source": "twitter",
      "utm_medium": "social",
      "utm_campaign": null,
      "expires_at": "2026-12-31T23:59:59Z",
      "ios_target": null,
      "android_target": null,
      "created_at": "2026-03-13T10:00:00Z",
      "updated_at": "2026-03-13T10:00:00Z"
    }
  ],
  "pagination": {
    "has_more": true,
    "cursor": "eyJpZCI6Imxua19hYmMxMjMifQ"
  }
}

Create a link

Create a new short link. If no slug is provided, a random one is generated. If no domain is specified, the workspace default domain is used.

POST/api/v1/links

Request body

Field	Type	Required	Description
url	string	Yes	The destination URL (must start with `https://`)
slug	string	No	Custom slug (4-64 chars). Auto-generated if omitted.
domain	string	No	Custom domain. Defaults to workspace domain.
title	string	No	Descriptive title for the link
tags	string[]	No	Array of tag strings for organizing links
utm_source	string	No	Appended to the destination URL as a UTM parameter
utm_medium	string	No	UTM medium parameter
utm_campaign	string	No	UTM campaign parameter
expires_at	string	No	ISO 8601 timestamp after which the link expires
password	string	No	Require this password before redirecting
ios_target	string	No	Redirect iOS users to this URL instead
android_target	string	No	Redirect Android users to this URL instead

Request

curl -X POST https://mask.pk/api/v1/links \
  -H "Authorization: Bearer mk_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/my-page",
    "slug": "my-link",
    "domain": "go.yourbrand.com",
    "title": "My Campaign Link",
    "tags": ["campaign-q1", "social"],
    "utm_source": "twitter",
    "utm_medium": "social",
    "expires_at": "2026-12-31T23:59:59Z"
  }'

Response — 201 Created

{
  "id": "lnk_abc123",
  "url": "https://example.com/my-page",
  "short_url": "https://go.yourbrand.com/my-link",
  "slug": "my-link",
  "domain": "go.yourbrand.com",
  "title": "My Campaign Link",
  "tags": ["campaign-q1", "social"],
  "clicks": 0,
  "utm_source": "twitter",
  "utm_medium": "social",
  "utm_campaign": null,
  "expires_at": "2026-12-31T23:59:59Z",
  "ios_target": null,
  "android_target": null,
  "created_at": "2026-03-13T10:00:00Z",
  "updated_at": "2026-03-13T10:00:00Z"
}

Get a link

Retrieve a single link by its ID. Returns all link fields including UTM parameters and device targets.

GET/api/v1/links/:id

Request

curl https://mask.pk/api/v1/links/lnk_abc123 \
  -H "Authorization: Bearer mk_live_abc123def456"

Response

{
  "id": "lnk_abc123",
  "url": "https://example.com/my-page",
  "short_url": "https://go.yourbrand.com/my-link",
  "slug": "my-link",
  "domain": "go.yourbrand.com",
  "title": "My Campaign Link",
  "tags": ["campaign-q1", "social"],
  "clicks": 142,
  "utm_source": "twitter",
  "utm_medium": "social",
  "utm_campaign": null,
  "expires_at": "2026-12-31T23:59:59Z",
  "ios_target": null,
  "android_target": null,
  "created_at": "2026-03-13T10:00:00Z",
  "updated_at": "2026-03-13T10:00:00Z"
}

Update a link

Update one or more fields on an existing link. Only the fields you include in the request body are modified. The slug and domain cannot be changed after creation.

PATCH/api/v1/links/:id

Request

curl -X PATCH https://mask.pk/api/v1/links/lnk_abc123 \
  -H "Authorization: Bearer mk_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/updated-page",
    "tags": ["campaign-q2", "email"],
    "expires_at": "2027-06-30T23:59:59Z"
  }'

Response

{
  "id": "lnk_abc123",
  "url": "https://example.com/updated-page",
  "short_url": "https://go.yourbrand.com/my-link",
  "slug": "my-link",
  "domain": "go.yourbrand.com",
  "title": "My Campaign Link",
  "tags": ["campaign-q2", "email"],
  "clicks": 142,
  "utm_source": "twitter",
  "utm_medium": "social",
  "utm_campaign": null,
  "expires_at": "2027-06-30T23:59:59Z",
  "ios_target": null,
  "android_target": null,
  "created_at": "2026-03-13T10:00:00Z",
  "updated_at": "2026-03-13T12:00:00Z"
}

Delete a link

Permanently delete a link. The short URL stops redirecting immediately. This action cannot be undone.

DELETE/api/v1/links/:id

Request

curl -X DELETE https://mask.pk/api/v1/links/lnk_abc123 \
  -H "Authorization: Bearer mk_live_abc123def456"

Response — 200 OK

{
  "deleted": true,
  "id": "lnk_abc123"
}