Skip to main content
GET
/
v1
/
links
List links
curl --request GET \
  --url https://{environment}.shortpen.com/v1/links \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "status_code": 200,
  "data": [
    {
      "id": 501,
      "url": "https://example.com/launch",
      "link": "https://go.shortpen.com/summer-2025",
      "short_url": "https://go.shortpen.com/summer-2025",
      "starred": false,
      "redirect_type": 301,
      "domain_id": 3,
      "workspace_id": 24,
      "organization_id": 3,
      "link_cloak": false,
      "hide_referer": false,
      "with_password": false,
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "title": "Launch landing page",
      "qr": "<string>",
      "folder_id": 42,
      "pixel_id": 123,
      "source_id": 123,
      "params": {},
      "social_share_title": "<string>",
      "social_share_description": "<string>",
      "social_share_image": "<string>"
    }
  ],
  "count": 25,
  "total": 142,
  "page": 1,
  "message": ""
}
Returns a paginated list of links belonging to the workspace associated with your API token. Use this endpoint to browse existing links, retrieve id values for editing, or synchronise link data with external systems.
The id field in each returned item is the url_id you need when calling the Edit Link endpoint.

​
Query parameters

ParameterTypeDefaultDescription
pageinteger1Page number (1-based).
limitinteger100Links per page. Maximum 100.
workspace_idintegerfirst workspaceWorkspace to scope results to.

​
Response payload

The response uses the standard envelope and adds pagination metadata:
  • data — array of link objects (see schema below).
  • count — number of items in the current page.
  • total — total number of links matching the query.
  • page — current page number.
Each item in data exposes the following properties:
FieldTypeDescription
idintegerUnique link identifier.
titlestringHuman-friendly title (if set).
urlstringDestination URL.
linkstringFully qualified link (domain + slug).
short_urlstringDeprecated — same value as link. Will be removed in a future version; migrate to link.
qrstring | nullBase64 QR code PNG if generated.
starredbooleanWhether the link is starred.
redirect_typeinteger301 or 302.
domain_idintegerDomain hosting the link.
folder_idinteger | nullFolder assignment.
pixel_idinteger | nullAssociated tracking pixel.
workspace_idintegerOwning workspace.
organization_idintegerOwning organization.
link_cloakbooleanWhether URL cloaking is active.
hide_refererbooleanWhether the referrer header is removed.
with_passwordbooleanWhether the link is password-protected.
paramsobject | nullQuery parameters appended to the destination.
social_share_titlestring | nullCustom OpenGraph title.
social_share_descriptionstring | nullCustom OpenGraph description.
social_share_imagestring | nullSocial preview image URL.
created_atstring (ISO 8601)When the link was created.
updated_atstring (ISO 8601)When the link was last modified.

Authorizations

​
Authorization
string
header
required

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

Query Parameters

​
page
integer
default:1

Page number for pagination.

Required range: x >= 1
​
limit
integer
default:100

Number of links per page (max 100).

Required range: 1 <= x <= 100
​
workspace_id
integer

Workspace ID to scope results. Defaults to the first workspace when omitted.

Response

Paginated list of links

​
success
boolean
required
Example:

true

​
status_code
integer
required
Example:

200

​
data
object[]
required
​
count
integer
required

Number of links returned in the current page.

Example:

25

​
total
integer
required

Total number of links matching the query.

Example:

142

​
page
integer
required

Current page number.

Example:

1

​
message
string
Example:

""