Skip to main content
PATCH
Update a link

Authorizations

Authorization
string
header
required

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

Path Parameters

id
string<uuid>
required

Link ID.

Body

Every field is optional. Sending null for a nullable field clears it; omitting a field leaves it unchanged.

url
string

New destination URL. Re-runs the destination safety scan.

Maximum string length: 2048
archived
boolean

Archive or restore the link.

title
string | null

Internal name for the link.

Maximum string length: 255
Example:

"Spring campaign"

description
string | null

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 | null

utm_source appended to the destination URL.

Maximum string length: 255
Example:

"newsletter"

utmMedium
string | null

utm_medium appended to the destination URL.

Maximum string length: 255
Example:

"email"

utmCampaign
string | null

utm_campaign appended to the destination URL.

Maximum string length: 255
Example:

"spring-2026"

utmTerm
string | null

utm_term appended to the destination URL.

Maximum string length: 255
utmContent
string | null

utm_content appended to the destination URL.

Maximum string length: 255
customUtmParams
object | null

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

Example:
password
string | null

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> | null

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> | null

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

schedulingTimezone
string | null

IANA timezone used to interpret the schedule in the UI.

Maximum string length: 64
Example:

"Asia/Kolkata"

fallbackUrl
string | null

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

Maximum string length: 2048
clickLimit
integer | null

Stop redirecting after this many clicks.

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

1000

iosUrl
string | null

Destination for iOS visitors. Requires the deviceTargeting plan feature.

Maximum string length: 2048
androidUrl
string | null

Destination for Android visitors. Requires the deviceTargeting plan feature.

Maximum string length: 2048
geoTargets
object[] | null

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

Turns geo targeting on. Set automatically when geoTargets is supplied unless explicitly false.

ogTitle
string | null

Open Graph title used in link previews.

Maximum string length: 255
ogDescription
string | null

Open Graph description used in link previews.

Maximum string length: 2000
ogImage
string | null

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> | null

UTM template to apply to this link.

cloakingEnabled
boolean

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

Response

The updated link.

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