API Reference

Short links (API)

Create and manage secure, branded short links with the Pxl API. Automate link generation, customize previews and track clicks to enhance your digital marketing efforts. Related guide: Creating short links.

This feature is available on all plans.

The short object

id: string

Unique identifier for each short link. The id is a text composite of the domain and route. Prepending https:// to the id will form a URL denoting the location of the short link.

route: string

The route of the short link.

consent: boolean

Specifies whether to request informed consent from visitors before storing cookies.

destination: string

Destination URL the short link will redirect to.

title: string

Title text shown in link previews.

description: string

Description text shown in link previews.

image: string

URL location of the image shown in link previews.

favicon: string

URL location of the favicon shown in browser for redirects.

clicks: number

Integer representation of the click count.

createdAt: date

Date representation of when the link was created in UTC+0.

updatedAt: date

Date representation of when the link was last updated in UTC+0. This attribute considers updates to the click count, and can therefore be used to infer the date and time of the most recent click.

To create a short link, you will make a POST request specifying the defining attributes.

POST https://api.pxl.to/api/v1/short

Parameters

destination: string — required

Destination URL of the new short link.

domain: string

The domain or subdomain of the new short link. Custom domains must be added in the dashboard before they can be used. Related guide: Creating custom domains.

route: string

The route of the new short link.

consent: boolean

Specifies whether to request informed consent from visitors before storing cookies. Requires company information on the admin page.

title: string

Title text shown in link previews.

description: string

Description text shown in link previews.

image: string

URL location of the image shown in link previews.

favicon: string

URL location of the favicon shown in browser for redirects.

Returns

Returns the short object.

Request

An example CURL request:

curl -X POST --compressed "https://api.pxl.to/api/v1/short" \
-H "Accept-Encoding: gzip" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
-d '{
    "destination": "example.com",
    "title": "Redirect",
    "description": "Descriptive text",
    "image": "https://example.com/image.png",
    "favicon": "https://example.com/favicon.ico"
}'

Response

An example JSON response:

{
  "data": {
    "id": "pxl.to/x8djds",
    "route": "x8djds",
    "destination": "https://example.com",
    "title": "Redirect",
    "description": "Descriptive text",
    "image": "https://example.com/image.png",
    "favicon": "https://example.com/favicon.ico",
    "consent": false,
    "clicks": 0,
    "createdAt": "2022-07-27T15:17:03.525Z",
    "updatedAt": "2022-07-27T15:17:03.525Z"
  }
}

To return a specific short link object, you will make a GET request specifying the URL encoded short id.

GET https://api.pxl.to/api/v1/short/:id

Parameters

No parameters.

Returns

Returns the short object.

Request

An example CURL request:

curl -X GET --compressed "https://api.pxl.to/api/v1/short/pxl.to%2Fx8djds" \
-H "Accept-Encoding: gzip" \
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

Response

An example JSON response:

{
  "data": {
    "id": "pxl.to/x8djds",
    "route": "x8djds",
    "destination": "https://example.com",
    "title": "Redirect",
    "description": "Descriptive text",
    "image": "https://example.com/image.png",
    "favicon": "https://example.com/favicon.ico",
    "consent": false,
    "clicks": 0,
    "createdAt": "2022-07-27T15:17:03.525Z",
    "updatedAt": "2022-07-27T15:17:03.525Z"
  }
}

To update attributes for a specific short, you will make a PUT request specifying the attributes to update and the URL encoded short id.

PUT https://api.pxl.to/api/v1/short/:id

Parameters

destination: string

Destination URL of the new short link.

consent: boolean

Specifies whether to request informed consent from visitors before storing cookies. Requires company information on the admin page.

title: string

Title text shown in link previews.

description: string

Description text shown in link previews.

image: string

URL location of the image shown in link previews.

favicon: string

URL location of the favicon shown in browser for redirects.

Returns

Returns the short object.

Request

An example CURL request:

curl -X PUT --compressed "https://api.pxl.to/api/v1/short/pxl.to%2Fx8djds" \
-H "Accept-Encoding: gzip" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
-d '{
    "destination": "https://google.com"
}'

Response

An example JSON response:

{
  "data": {
    "id": "pxl.to/x8djds",
    "route": "x8djds",
    "destination": "https://google.com",
    "title": "Redirect",
    "description": "Descriptive text",
    "image": "https://example.com/image.png",
    "favicon": "https://example.com/favicon.ico",
    "consent": false,
    "clicks": 0,
    "createdAt": "2022-07-27T15:17:03.525Z",
    "updatedAt": "2022-07-27T15:17:03.525Z"
  }
}

To delete a specific short link, you will make a DELETE request specifying the URL encoded short id.

DELETE https://api.pxl.to/api/v1/short/:id

Parameters

No parameters.

Returns

Returns the number of records affected.

Request

An example CURL request:

curl -X DELETE --compressed "https://api.pxl.to/api/v1/short/pxl.to%2Fx8djds" \
-H "Accept-Encoding: gzip" \
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

Response

An example JSON response:

{
  "data": {
    "raw": [],
    "affected": 1
  }
}

To return all short links associated with your organisation, you will make a GET request.

GET https://api.pxl.to/api/v1/short

Parameters

take: number

The number of records to return, with a minimum value of 1 and a maximum value of 50. Defaults to 50.

skip: number

The number of records to skip, with a minimum value of 0 and a maximum value of 50. Defaults to 0.

Returns

Returns a list of every short object associated with your organisation.

Request

An example CURL request:

curl -X GET --compressed "https://api.pxl.to/api/v1/short?take=2&skip=10" \
-H "Accept-Encoding: gzip" \
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \

Response

An example JSON response:

{
  "data": [
    {
      "id": "pxl.to/x8djds",
      "route": "x8djds",
      "destination": "https://example.com",
      "title": "Redirect",
      "description": "Descriptive text",
      "image": "https://example.com/image.png",
      "favicon": "https://example.com/favicon.ico",
      "consent": false,
      "clicks": 0,
      "createdAt": "2022-07-27T15:17:03.525Z",
      "updatedAt": "2022-07-27T15:17:03.525Z"
    },
    {
      "id": "pxl.to/bing/preview",
      "route": "bing/preview",
      "destination": "https://bing.com/search?q=preview",
      "title": "Redirect",
      "description": "Descriptive text",
      "image": "https://bing.com/image.png",
      "favicon": "https://bing.com/favicon.ico",
      "consent": true,
      "clicks": 32,
      "createdAt": "2022-02-21T12:11:03.545Z",
      "updatedAt": "2022-02-21T12:11:03.545Z"
    }
  ]
}
Previous
Getting started
Next
Analytics