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": {
    "short_url": "https://go.shortpen.com/summer-2025",
    "created": true,
    "qr": "<string>"
  },
  "message": ""
}
Create or update a 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.short_url — fully qualified link combining the selected domain and slug.
  • data.qr — base64-encoded PNG when generate_qr evaluates to true; otherwise null.
  • data.created — distinguishes between newly created (true) and updated (false) links.
If a monthly quota (URLs, 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.

Authorizations

​
Authorization
string
header
required

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

Body

application/json
​
url
string<uri>
required

Destination URL that will be shortened.

Example:

"https://example.com/launch"

​
domain_id
integer
required

ID of the domain to use for the new short 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 new short 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 short 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 short 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

Short link generated successfully

​
success
boolean
required
Example:

true

​
status_code
integer
required
Example:

200

​
data
object
required
​
message
string
Example:

""