Skip to main content
PUT
/
v1
/
links
curl --request PUT \
  --url https://{environment}.shortpen.com/v1/links \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url_id": 501,
  "url": "https://example.com/new-destination",
  "domain_id": 1
}
'
{
  "success": true,
  "status_code": 200,
  "data": {
    "link": "https://go.shortpen.com/summer-2025",
    "short_url": "https://go.shortpen.com/summer-2025",
    "created": true,
    "qr": "<string>"
  },
  "message": ""
}
Update an existing link by supplying its url_id along with only the fields you want to change. Omitted fields retain their current values, so you can make targeted updates without resending the entire link configuration.
You can find the url_id of any link by calling GET /v1/links — the id field in each item is the value you need.

​
How it works

Only url_id is strictly required. You must also include at least one additional field to specify what to change — otherwise the API returns a 400 error. The edit endpoint shares the same internal logic as creation. When url_id is present in the request, the API locates the existing link and applies the supplied fields as an update. Any field you omit is preserved from the existing link, including settings like redirect type, password protection, cloaking, tracking, and social previews. Both PUT and PATCH methods are accepted and behave identically.

​
Request body

FieldTypeRequiredDescription
url_idinteger✅ID of the link to update.
urlstring (URI)New destination URL.
domain_idintegerDomain that hosts the link. Must be active for the organization.
workspace_idintegerOverrides the default workspace.
titlestringHuman-friendly title for the link.
custom_slugstringBranded slug. Plan limits and reserved-word checks apply.
folder_idintegerAssigns the link to a folder.
paramobjectQuery parameters appended to the destination URL (e.g. UTM tags).
generate_qrbooleanGenerates or regenerates a QR code for the link.
enable_trackingbooleanAssociates the link with a tracking pixel. Requires pixel_id.
pixel_idintegerPixel identifier for event tracking.
redirect_typeinteger (301 or 302)HTTP redirect status.
link_cloakbooleanCloaks the destination URL.
hide_refererbooleanRemoves the referrer header.
with_passwordbooleanEnables password protection. Pair with url_password.
url_passwordstringPassword required to access the link.
r, g, binteger (0-255)RGB color channels for QR codes.
uploaded_logo_typeenum(none, custom, uploaded)Logo embedded in QR codes.
uploaded_logo_database64 stringCustom logo image when uploaded_logo_type is uploaded.
social_share_titlestringOverrides the OpenGraph title.
social_share_descriptionstringOverrides the OpenGraph description.
social_share_image_database64 stringCustom social preview image.

​
Response highlights

  • data.link — the fully qualified link after the update.
  • data.short_url — same value as link. Deprecated — will be removed in a future version; migrate to data.link.
  • data.qr — base64-encoded QR PNG when a QR code exists; otherwise null.
  • data.created — always false for edit operations, confirming the link was updated rather than newly created.

​
Error handling

StatusMeaning
400Validation error — url_id is missing, or no field to update was provided.
401Missing or invalid API token.
404No link found for the given url_id in the authenticated organization.
429A monthly feature quota has been reached (e.g. QR codes, custom slugs).
500Unexpected error while updating the link. Retry the request.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Only url_id is required. At least one additional field must be provided to specify what to change. Omitted fields retain their current values.

​
url_id
integer
required

ID of the existing link to update. Retrieve this from the List Links endpoint or the link creation response.

​
url
string<uri>

Destination URL the link redirects to.

Example:

"https://example.com/launch"

​
domain_id
integer

ID of the domain that hosts the link.

​
workspace_id
integer

Workspace ID. Defaults to the first workspace associated with the organization when omitted.

​
title
string

Optional human-friendly title for the link.

​
custom_slug
string

Custom slug appended to the domain instead of an auto-generated code.

​
folder_id
integer

Folder to assign the link to.

​
param
object

Query parameters appended to the destination URL.

​
generate_qr
boolean
default:false

Whether to create a QR code for the link.

​
enable_tracking
boolean
default:false

Set to true to associate the link with the specified pixel for event tracking.

​
pixel_id
integer

Pixel ID used when tracking is enabled.

​
redirect_type
enum<integer>
default:301

HTTP redirect status applied when visitors follow the link.

Available options:
301,
302
​
link_cloak
boolean

If true, cloaks the destination URL.

​
hide_referer
boolean

If true, removes the referrer header for visitors.

​
with_password
boolean

Protects the link behind a password.

​
url_password
string

Password required when with_password is true.

​
r
integer

Red channel used when generating QR codes.

Required range: 0 <= x <= 255
Example:

45

​
g
integer

Green channel used when generating QR codes.

Required range: 0 <= x <= 255
Example:

151

​
b
integer

Blue channel used when generating QR codes.

Required range: 0 <= x <= 255
Example:

123

​
uploaded_logo_type
enum<string>
default:none

Controls which logo is embedded inside generated QR codes.

Available options:
none,
custom,
uploaded
​
uploaded_logo_data
string<byte>

Base64-encoded file used when uploaded_logo_type is uploaded.

​
social_share_title
string

Overrides the title shown in social previews.

​
social_share_description
string

Overrides the description shown in social previews.

​
social_share_image_data
string<byte>

Base64-encoded image used for the social preview.

Response

Link updated successfully

​
success
boolean
required
Example:

true

​
status_code
integer
required
Example:

200

​
data
object
required
​
message
string
Example:

""