Skip to main content
POST
Create a link

Authorizations

Authorization
string
header
required

Workspace API key, sent as Authorization: Bearer lk_live_….

Body

url
string
required

Destination URL. Scanned for malware and phishing before the link is created.

Maximum string length: 2048
Example:

"https://acme.com/pricing"

title
string
required

Internal name for the link.

Maximum string length: 255
Example:

"Spring campaign"

description
string

Internal description.

Maximum string length: 2000
customSlug
string

Short code to use instead of a generated one. Letters, numbers, hyphens and underscores only. Short codes are globally unique across every workspace, so a code taken elsewhere returns 409.

Maximum string length: 50
Pattern: ^[a-zA-Z0-9_-]+$
Example:

"spring-sale"

utmSource
string

utm_source appended to the destination URL.

Maximum string length: 255
Example:

"newsletter"

utmMedium
string

utm_medium appended to the destination URL.

Maximum string length: 255
Example:

"email"

utmCampaign
string

utm_campaign appended to the destination URL.

Maximum string length: 255
Example:

"spring-2026"

utmTerm
string

utm_term appended to the destination URL.

Maximum string length: 255
utmContent
string

utm_content appended to the destination URL.

Maximum string length: 255
customUtmParams
object

Workspace-defined UTM parameters, keyed by the parameter code configured under Parameters. Validated against the workspace's UTM rules.

Example:
password
string

Plain-text password the visitor must enter. Stored as a bcrypt hash and never returned — responses expose hasPassword instead. Counts against the passwordProtectedLinks plan quota.

Maximum string length: 200
expiresAt
string<date-time>

ISO 8601 instant after which the link stops redirecting. Requires the linkScheduling plan feature.

Example:

"2026-12-31T00:00:00.000Z"

scheduledAt
string<date-time>

ISO 8601 instant before which the link does not redirect yet. Requires the linkScheduling plan feature.

schedulingTimezone
string

IANA timezone used to interpret the schedule in the UI.

Maximum string length: 64
Example:

"Asia/Kolkata"

fallbackUrl
string

Where to send visitors once the link is expired, not yet live, or over its click limit.

Maximum string length: 2048
clickLimit
integer

Stop redirecting after this many clicks.

Required range: 1 <= x <= 2147483647
Example:

1000

iosUrl
string

Destination for iOS visitors. Requires the deviceTargeting plan feature.

Maximum string length: 2048
androidUrl
string

Destination for Android visitors. Requires the deviceTargeting plan feature.

Maximum string length: 2048
geoTargets
object[]

Country-specific destinations. Pick a country and enter the URL visitors from that country are sent to. Requires the geoTargeting plan feature. Every target URL runs through the same safety scan as url. A map of country code to URL ({"US": "https://acme.com/us"}) is also accepted.

Maximum array length: 100
Example:
geoTargetingEnabled
boolean
default:true

Turns geo targeting on. Defaults to true when geoTargets is supplied; set false to save the targets without activating them.

ogTitle
string

Open Graph title used in link previews.

Maximum string length: 255
ogDescription
string

Open Graph description used in link previews.

Maximum string length: 2000
ogImage
string

Preview image for the link. Send an absolute URL, or upload the file inline by posting multipart/form-data with the JSON body in a payload part and the image in an ogImageFile part (PNG/JPEG/WebP, 5 MB max).

Maximum string length: 2048
comments
string

Internal note. Never shown to visitors.

Maximum string length: 2000
folderId
string<uuid> | null

Folder to file the link under. Requires the tagsAndFolders plan feature.

tagIds
string<uuid>[]

Tags to attach. Every ID must belong to the same workspace. Requires the tagsAndFolders plan feature.

pixelIds
string<uuid>[]

Tracking pixels to fire on click. Every ID must belong to the same workspace.

domainId
string<uuid>

Custom domain to build the short URL from. Defaults to the workspace's default domain, then to the system domain.

templateId
string<uuid>

UTM template to apply to this link.

cloakingEnabled
boolean

Serve the destination inside a frame instead of redirecting. Requires the linkCloaking plan feature.

Response

Link created.

Full link record as returned by GET /links/{id}, PATCH /links/{id}, DELETE /links/{id} and POST /links/upsert.

The stored password is a bcrypt hash and is never serialised — the boolean hasPassword is returned in its place.

id
string<uuid>
url
string

Destination URL.

Example:

"https://acme.com/pricing"

shortCode
string

Path segment of the short link.

Example:

"spring-sale"

title
string | null
Example:

"Spring campaign"

description
string | null
utmSource
string | null
Example:

"newsletter"

utmMedium
string | null
Example:

"email"

utmCampaign
string | null
Example:

"spring-2026"

utmTerm
string | null
utmContent
string | null
customUtmParams
object | null

Workspace-defined UTM parameters, keyed by parameter code.

hasPassword
boolean

true when a password gate is set on the link.

expiresAt
string<date-time> | null

After this instant the link stops redirecting.

scheduledAt
string<date-time> | null

Before this instant the link does not redirect yet.

schedulingTimezone
string | null
Example:

"Asia/Kolkata"

fallbackUrl
string | null

Used when the link is expired, not yet live, or click-limited.

clickLimit
integer | null
Example:

1000

clicks
integer
Example:

42

lastClickAt
string<date-time> | null
iosUrl
string | null

Deep link opened for iOS visitors.

androidUrl
string | null

Deep link opened for Android visitors.

geoTargets
object | null

ISO 3166-1 alpha-2 country code to destination URL.

Example:
geoTargetingEnabled
boolean
ogTitle
string | null
ogDescription
string | null
ogImage
string | null

S3 key or absolute URL of the preview image.

favicon
string | null
comments
string | null

Internal note. Never shown to visitors.

qrCodeEnabled
boolean
qrFgColor
string | null
Example:

"#000000"

qrBgColor
string | null
Example:

"#ffffff"

qrSize
integer | null
Example:

512

qrDesign
object | null
cloakingEnabled
boolean

Serve the destination inside a frame instead of redirecting.

archived
boolean
isActive
boolean
deletedAt
string<date-time> | null

Set by DELETE /links/{id}. Deleted links are never returned by list endpoints.

safetyStatus
string

Result of the destination safety scan.

Example:

"safe"

safetyCheckedAt
string<date-time> | null
safetyReason
string | null
folderId
string<uuid> | null
domainId
string<uuid> | null
templateId
string<uuid> | null
workspaceId
string<uuid>
createdById
string<uuid> | null
updatedById
string<uuid> | null
createdAt
string<date-time>
updatedAt
string<date-time>
tags
object[]
pixels
object[]
domain
object | null