Skip to main content
POST
/
v1
/
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": ""
}
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

FieldTypeRequiredDescription
urlstring (URI)✅Destination URL. Missing schemes are automatically prefixed with https://.
domain_idinteger✅Domain that will host the link. The API validates ownership and plan eligibility.
workspace_idintegerOverrides the default workspace inferred from the token. Useful when a key has access to multiple workspaces.
titlestringOptional human-friendly title for reporting.
custom_slugstringBranded slug appended to the domain instead of an auto-generated code. Plan limits and reserved-word checks apply.
folder_idintegerAssigns the link to an existing folder.
paramobjectAdditional query parameters appended to the destination URL (for example UTM tags). Empty values are stripped automatically.
generate_qrbooleanGenerates and returns a base64-encoded QR code alongside the link.
enable_trackingbooleanLinks the URL to a tracking pixel. Requires pixel_id.
pixel_idintegerPixel identifier retrieved via the resources endpoint.
redirect_typeinteger (301 or 302)Controls whether redirects are permanent or temporary. Defaults to 301.
link_cloakbooleanCloaks the destination URL.
hide_refererbooleanRemoves the referrer header so destination sites do not see the original source.
with_passwordbooleanProtects the link behind a password. Pair with url_password.
url_passwordstringPassword required to resolve the link when with_password is true.
r, g, binteger (0-255)RGB color channels used when a QR code is generated.
uploaded_logo_typeenum(none, custom, uploaded)Controls the logo embedded inside generated QR codes. custom reuses the organization logo, uploaded expects uploaded_logo_data.
uploaded_logo_database64 stringBase64-encoded image used for the QR logo when uploaded_logo_type is uploaded.
social_share_titlestringOverrides the OpenGraph title used when the link is shared.
social_share_descriptionstringOverrides the OpenGraph description.
social_share_image_database64 stringCustom social preview image (PNG/JPEG/SVG).
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.

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

​
success
boolean
required
Example:

true

​
status_code
integer
required
Example:

200

​
data
object
required
​
message
string
Example:

""