Create Link

POST

generate

curl --request POST \
  --url https://{environment}.shortpen.com/v1/generate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://example.com/launch",
  "domain_id": 1,
  "workspace_id": 24,
  "title": "Launch landing page"
}
'

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

Create a new link inside the workspace tied to your API token. The endpoint shares logic with the dashboard, so all plan limits, QR quotas, and custom domain validations apply here too.

domain_id must point to a domain that is active for the organization and visible to the authenticated workspace. Use POST /v1/get with resource: "domain" to retrieve the allowed IDs.

Request body

Field	Type	Required	Description
`url`	string (URI)	✅	Destination URL. Missing schemes are automatically prefixed with `https://`.
`domain_id`	integer	✅	Domain that will host the link. The API validates ownership and plan eligibility.
`workspace_id`	integer		Overrides the default workspace inferred from the token. Useful when a key has access to multiple workspaces.
`title`	string		Optional human-friendly title for reporting.
`custom_slug`	string		Branded slug appended to the domain instead of an auto-generated code. Plan limits and reserved-word checks apply.
`folder_id`	integer		Assigns the link to an existing folder.
`param`	object		Additional query parameters appended to the destination URL (for example UTM tags). Empty values are stripped automatically.
`generate_qr`	boolean		Generates and returns a base64-encoded QR code alongside the link.
`enable_tracking`	boolean		Links the URL to a tracking pixel. Requires `pixel_id`.
`pixel_id`	integer		Pixel identifier retrieved via the resources endpoint.
`redirect_type`	integer (301 or 302)		Controls whether redirects are permanent or temporary. Defaults to `301`.
`link_cloak`	boolean		Cloaks the destination URL.
`hide_referer`	boolean		Removes the referrer header so destination sites do not see the original source.
`with_password`	boolean		Protects the link behind a password. Pair with `url_password`.
`url_password`	string		Password required to resolve the link when `with_password` is true.
`r`, `g`, `b`	integer (0-255)		RGB color channels used when a QR code is generated.
`uploaded_logo_type`	enum(`none`, `custom`, `uploaded`)		Controls the logo embedded inside generated QR codes. `custom` reuses the organization logo, `uploaded` expects `uploaded_logo_data`.
`uploaded_logo_data`	base64 string		Base64-encoded image used for the QR logo when `uploaded_logo_type` is `uploaded`.
`social_share_title`	string		Overrides the OpenGraph title used when the link is shared.
`social_share_description`	string		Overrides the OpenGraph description.
`social_share_image_data`	base64 string		Custom social preview image (PNG/JPEG/SVG).
`tag_ids`	integer[]		IDs of the tags to attach to the new link. Tags must belong to the same workspace and organization; unknown IDs are ignored. A JSON-encoded string such as `"[12,18]"` is also accepted.
`notes`	string		Add a custom note to the new link. 300 characters max.

Need to attach a stored social preview image that already lives on ShortPen? Set social_share_image_data to the base64 payload provided by previous uploads or send the legacy social_share_image_session value.

Response highlights

data.link — fully qualified link combining the selected domain and slug.
data.short_url — same value as link. Deprecated — will be removed in a future version; migrate to data.link.
data.qr — base64-encoded PNG when generate_qr evaluates to true; otherwise null.
data.created — true for newly created links.

If a monthly quota (links, QR codes, custom slugs, etc.) has been reached, the API responds with HTTP 429 and a descriptive message so you can trigger a plan upgrade workflow or notify an operator.

Need to update an existing link instead? Use the Edit Link endpoint with PUT or PATCH /v1/links.

Authorizations

Authorization

string

header

required

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

Body

application/json

Common fields shared between link creation and editing.

url

string<uri>

required

Destination URL the link redirects to.

Example:

"https://example.com/launch"

domain_id

integer

required

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 created successfully

success

boolean

required

Example:

true

status_code

integer

required

Example:

200

data

object

required

Show child attributes

message

string

Example:

""

Edit LinkUpdates an existing link identified by `url_id`. Only `url_id` is required — include at least one additional field to specify what to change. Omitted fields retain their current values. The API enforces the same plan limits and feature checks as creation.

curl --request POST \
  --url https://{environment}.shortpen.com/v1/generate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://example.com/launch",
  "domain_id": 1,
  "workspace_id": 24,
  "title": "Launch landing page"
}
'

{
  "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

Request body

Response highlights

Authorizations

Body

Response

​Request body

​Response highlights

Authorizations

Body

Response

Request body

Response highlights