Edit Link

PUT

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

{
  "success": false,
  "status_code": 401,
  "message": "There was an error while processing your request.",
  "data": "<unknown>"
}

{
  "success": false,
  "status_code": 401,
  "message": "There was an error while processing your request.",
  "data": "<unknown>"
}

{
  "success": false,
  "status_code": 401,
  "message": "There was an error while processing your request.",
  "data": "<unknown>"
}

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

Field	Type	Required	Description
`url_id`	integer	✅	ID of the link to update.
`url`	string (URI)		New destination URL.
`domain_id`	integer		Domain that hosts the link. Must be active for the organization.
`workspace_id`	integer		Overrides the default workspace.
`title`	string		Human-friendly title for the link.
`custom_slug`	string		Branded slug. Plan limits and reserved-word checks apply.
`folder_id`	integer		Assigns the link to a folder.
`param`	object		Query parameters appended to the destination URL (e.g. UTM tags).
`generate_qr`	boolean		Generates or regenerates a QR code for the link.
`enable_tracking`	boolean		Associates the link with a tracking pixel. Requires `pixel_id`.
`pixel_id`	integer		Pixel identifier for event tracking.
`redirect_type`	integer (301 or 302)		HTTP redirect status.
`link_cloak`	boolean		Cloaks the destination URL.
`hide_referer`	boolean		Removes the referrer header.
`with_password`	boolean		Enables password protection. Pair with `url_password`.
`url_password`	string		Password required to access the link.
`r`, `g`, `b`	integer (0-255)		RGB color channels for QR codes.
`uploaded_logo_type`	enum(`none`, `custom`, `uploaded`)		Logo embedded in QR codes.
`uploaded_logo_data`	base64 string		Custom logo image when `uploaded_logo_type` is `uploaded`.
`social_share_title`	string		Overrides the OpenGraph title.
`social_share_description`	string		Overrides the OpenGraph description.
`social_share_image_data`	base64 string		Custom social preview image.
`tag_ids`	integer[]		Replaces the link’s tags with the supplied set. See Updating tags below.
`notes`	string		Edit the custom note of the link. 300 characters max.

Updating tags

The tag_ids field follows the same “only what you send” rule as the rest of the edit endpoint, with one nuance worth calling out:

Omit tag_ids — the link’s existing tags are left untouched.
Send an array of IDs — the link’s tags are replaced with exactly that set ([12, 18] keeps only tags 12 and 18).
Send an empty array [] — every tag is removed from the link.

Tags must belong to the same workspace and organization as the link; unknown IDs are silently ignored. A JSON-encoded string such as "[12,18]" is also accepted.

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

Status	Meaning
400	Validation error — `url_id` is missing, or no field to update was provided.
401	Missing or invalid API token.
404	No link found for the given `url_id` in the authenticated organization.
429	A monthly feature quota has been reached (e.g. QR codes, custom slugs).
500	Unexpected 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.

Show child attributes

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.

integer

Red channel used when generating QR codes.

Required range: 0 <= x <= 255

Example:

45

integer

Green channel used when generating QR codes.

Required range: 0 <= x <= 255

Example:

151

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.

Overrides the title shown in social previews.

Overrides the description shown in social previews.

Base64-encoded image used for the social preview.

tag_ids

integer[]

IDs of the tags to associate with the link. On creation the listed tags are attached. On edit, sending this field replaces the link's tags with the supplied set — an empty array clears every tag, while omitting the field entirely leaves existing tags untouched. Tags must belong to the same workspace and organization; unknown IDs are ignored. A JSON-encoded string of IDs (e.g. "[12,18]") is also accepted for backwards compatibility.

Example:

[12, 18]

notes

string

Overrides the private notes shown in ShortPen Links/QRs list.

Response

Link updated successfully

success

boolean

required

Example:

true

status_code

integer

required

Example:

200

data

object

required

Show child attributes

message

string

Example:

""

Delete LinkDeletes one or more links owned by the authenticated organization. Provide `url_id` as a single integer or an array of integers. Links are soft-deleted, so they immediately disappear from listings while their historical analytics remain recoverable.

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

{
  "success": false,
  "status_code": 401,
  "message": "There was an error while processing your request.",
  "data": "<unknown>"
}

{
  "success": false,
  "status_code": 401,
  "message": "There was an error while processing your request.",
  "data": "<unknown>"
}

{
  "success": false,
  "status_code": 401,
  "message": "There was an error while processing your request.",
  "data": "<unknown>"
}

API reference

Core

Links

Resources

How it works

Request body

Updating tags

Response highlights

Error handling

Authorizations

Body

Response

​How it works

​Request body

​Updating tags

​Response highlights

​Error handling

Authorizations

Body

Response

How it works

Request body

Updating tags

Response highlights

Error handling