Link API | How to Shorten Links using the Y.GY API

This is the main API to create new short links with y.gy.

POST/api/v1/link

Create a Short Link

Required attributes

Name
destination_url
Type
string
Description
The short link will redirect to this destination URL

Optional attributes

Name
domain
Type
string
Description
This is the domain of the short link. If you don't send any values, we assume the domain is y.gy. You can add a custom domain (or sub-domain), but this has to be verified via the y.gy dashboard first.
Name
suffix
Type
string
Description
The end of the link. If the suffix is 123, the short link might look like y.gy/123
Name
password
Type
string
Description
If you want to password-protect your page, you can include a password here.
Name
og_title
Type
string
Description
This is the title that shows on social link previews on social media.
Name
og_description
Type
string
Description
This is the description that shows on social link previews on social media.
Name
og_image
Type
string
Description
This is the image that shows on social link previews on social media. The image needs to be a URL to an image object, for example, https://dev-test-bucket.s3.amazonaws.com/be2219f6-bc01-424d-b040-7e5f5f688f3c.png
Name
expiration_date
Type
datetime
Description
If you want the link to be inaccessible after a given date, you can add the datetime of that here.
Name
qr_code_foreground_hex
Type
string
Description
We return a QR code with all short links. You can optionally add a foreground color for the QR PNG/SVG. Please add a full hex including the # -- for example: #CF245A.
Name
qr_code_background_hex
Type
string
Description
We return a QR code with all short links. You can optionally add a background color for the QR PNG/SVG. Please add a full hex including the # -- for example: #CF245A.
Name
name
Type
string
Description
This is an optional descriptive internal name or title associated with the link
Name
tags
Type
array
Description
This is an array of tag ids, that corresponds to the tags you want to add to the link, as returned by the tags API.
Name
android_link_destination
Type
string
Description
If provided, the short link will redirect to this destination URL on Android devices.
Name
ios_link_destination
Type
string
Description
If provided, the short link will redirect to this destination URL on iOS devices.
Name
webhook_url
Type
string
Description
URL to which real-time updates get posted via webhook integration.
Name
webhook_auth_key
Type
string
Description
The authentication key is used to secure webhook interactions.

Query Parameters

Name
disable_png=true
Type
string
Description
This query parameter allows you to optionally turn off creating a PNG version of the QR code for the link, creating only the SVG version of the QR code. It can be very useful when you want to frequently generate a large number of links (e.g., 500 links per minute). The PNG QR code creation process takes relatively longer, so disabling it will make things way faster.

Response

The response is a Link object, as shown in the response.

Request

POST

/api/v1/link

curl --request POST \
--url https://api.y.gy/api/v1/link \
--header 'Content-Type: application/json' \
--data '{
"destination_url": "x.com/getwaitlist",
"domain": "wait.list",
"suffix": "social",
"tags": [1]
}'

Link Response Example

{
    "id": 12,
    "created_at": "2023-09-11_03-33-06",
    "domain": "https://wait.list",
    "suffix": "social",
    "organization_id": 11,
    "og_title": null,
    "og_description": null,
    "og_image": null,
    "destination_url": "https://x.com/getwaitlist",
    "qr_code_svg": "<svg width=\"29mm\" height=\"29mm\" [...] </svg>",
    "qr_code_png": "https://dev-yotto.s3.amazonaws.com/be2219f6-bc01-424d-b040-7e5f5f688f3c.png",
    "url": "https://wait.list/social"
    "expiration_date": null,
    "qr_code_foreground_hex": "#ffffff",
    "qr_code_background_hex": "#000000",
    "has_password": false,
    "android_link_destination": null,
    "bot_protection": null,
    "captcha": null,
    "ios_link_destination": null,
    "name": null,
    "tags": [
        {
          "created_at": "2023-09-11_02-33-06",
          "id": 1,
          "name": "Tag 1",
          "organization_id": 1
        }
    ],
    "password": null,
    "webhook_auth_key": null,
    "webhook_url": null,
    "zapier_key": "a5U8OaWIkViD741bFRiFKUPidhnqWudv_egsIKRWk4w",
    "zapier_webhook_url_new_click": null
}

GET/api/v1/link/<id>

Get a Short Link

Name
id
Type
string
Description
The ID of the link as returned by the y.gy API originally

Response

The response is a link object, as shown in the response.

Request

GET

/api/v1/link/<id>

curl --request GET \
--url https://api.y.gy/api/v1/link/12\
--header 'Content-Type: application/json' \

Link Response Example

{
    "id": 12,
    "created_at": "2023-09-11_03-33-06",
    "domain": "https://wait.list",
    "suffix": "social",
    "organization_id": 11,
    "og_title": null,
    "og_description": null,
    "og_image": null,
    "destination_url": "https://x.com/getwaitlist",
    "qr_code_svg": "<svg width=\"29mm\" height=\"29mm\" [...] </svg>",
    "qr_code_png": "https://dev-yotto.s3.amazonaws.com/be2219f6-bc01-424d-b040-7e5f5f688f3c.png",
    "url": "https://wait.list/social"
    "expiration_date": null,
    "qr_code_foreground_hex": "#ffffff",
    "qr_code_background_hex": "#000000",
    "has_password": false,
    "android_link_destination": null,
    "bot_protection": null,
    "captcha": null,
    "ios_link_destination": null,
    "name": null,
    "tags": [
        {
          "created_at": "2023-09-11_02-33-06",
          "id": 1,
          "name": "Tag 1",
          "organization_id": 1
        }
      ],
    "password": null,
    "webhook_auth_key": null,
    "webhook_url": null,
    "zapier_key": "a5U8OaWIkViD741bFRiFKUPidhnqWudv_egsIKRWk4w",
    "zapier_webhook_url_new_click": null
}

GET/api/v1/link

Get all links

Optional Attributes

Name
limit
Type
number
Description
The total number of links you want to be returned from the API, which defaults to 25.

Name
offset
Type
number
Description
The number of links to skip before counting the total number of links to return.

Response

The response is an object containing an array of link objects along with the total count of links, as demonstrated in the response.

Request

GET

/api/v1/link

curl --request GET \
--url https://api.y.gy/api/v1/link\
--header 'Content-Type: application/json' \

Link Response Example

{
    "links" : [
{
    "id": 12,
    "created_at": "2023-09-11_03-33-06",
    "domain": "https://wait.list",
    "suffix": "social",
    "organization_id": 11,
    "og_title": null,
    "og_description": null,
    "og_image": null,
    "destination_url": "https://x.com/getwaitlist",
    "qr_code_svg": "<svg width=\"29mm\" height=\"29mm\" [...] </svg>",
    "qr_code_png": "https://dev-yotto.s3.amazonaws.com/be2219f6-bc01-424d-b040-7e5f5f688f3c.png",
    "url": "https://wait.list/social"
    "expiration_date": null,
    "qr_code_foreground_hex": "#ffffff",
    "qr_code_background_hex": "#000000",
    "has_password": false,
    "android_link_destination": null,
    "bot_protection": null,
    "captcha": null,
    "ios_link_destination": null,
    "name": null,
    "tags": [
        {
          "created_at": "2023-09-11_02-33-06",
          "id": 1,
          "name": "Tag 1",
          "organization_id": 1
        }
      ],
    "password": null,
    "webhook_auth_key": null,
    "webhook_url": null,
    "zapier_key": "a5U8OaWIkViD741bFRiFKUPidhnqWudv_egsIKRWk4w",
    "zapier_webhook_url_new_click": null
}
    ],
    "total_links" : 1
}

PATCH/api/v1/link/<id>

Patch a short link

Required Attributes

Name
id
Type
string
Description
The ID of the link as returned by the y.gy API originally

Optional attributes

Name
destination_url
Type
string
Description
The short link will redirect to this destination URL
Name
password
Type
string
Description
If you want to password-protect your page, you can include a password here.
Name
og_title
Type
string
Description
This is the title that shows on social link previews on social media.
Name
og_description
Type
string
Description
This is the description that shows on social link previews on social media.
Name
og_image
Type
string
Description
This is the image that shows on social link previews on social media. The image needs to be a URL to an image object, for example, https://dev-test-bucket.s3.amazonaws.com/be2219f6-bc01-424d-b040-7e5f5f688f3c.png
Name
expiration_date
Type
datetime
Description
If you want the link to be inaccessible after a given date, you can add the datetime of that here.
Name
qr_code_foreground_hex
Type
string
Description
Adds a foreground color for the QR PNG/SVG. Please add a full hex including the # -- for example: #CF245A.
Name
qr_code_background_hex
Type
string
Description
Adds a background color for the QR PNG/SVG. Please add a full hex including the # -- for example: #CF245A.
Name
name
Type
string
Description
A descriptive internal name or title associated with the link
Name
add_tags
Type
array
Description
An array of tag ids, that corresponds to the tags you want to add to the link, as returned by the tags API.
Name
remove_tags
Type
array
Description
An array of tag ids, that corresponds to the tags you want to remove from the link, as returned by the tags API.
Name
android_link_destination
Type
string
Description
If provided, the short link will redirect users to this destination URL on Android devices.
Name
ios_link_destination
Type
string
Description
If provided, The short link will redirect to this destination URL on ios devices.
Name
bot_protection
Type
boolean
Description
If enabled, bots are disallowed from accessing the destination_url through the link.
Name
captcha
Type
boolean
Description
If enabled, it requires that a captcha be passed before redirecting to the destination_url.
Name
webhook_url
Type
string
Description
URL to which real-time updates get posted via webhook integration.
Name
webhook_auth_key
Type
string
Description
The authentication key is used to secure webhook interactions.

Response

The response is a link object, as shown in the response.

Request

PATCH

/api/v1/link/<id>

curl --request PATCH \
--url https://api.y.gy/api/v1/link/12 \
--header 'Content-Type: application/json' \
--data '{
"destination_url": "x.com/getwaitlist",
"add_tags": [2],
"remove_tags": [1],
}'

Link Response Example


{
    "id": 12,
    "created_at": "2023-09-11_03-33-06",
    "domain": "https://wait.list",
    "suffix": "social",
    "organization_id": 11,
    "og_title": null,
    "og_description": null,
    "og_image": null,
    "destination_url": "https://x.com/getwaitlist",
    "qr_code_svg": "<svg width=\"29mm\" height=\"29mm\" [...] </svg>",
    "qr_code_png": "https://dev-yotto.s3.amazonaws.com/be2219f6-bc01-424d-b040-7e5f5f688f3c.png",
    "url": "https://wait.list/social"
    "expiration_date": null,
    "qr_code_foreground_hex": "#ffffff",
    "qr_code_background_hex": "#000000",
    "has_password": false,
    "android_link_destination": null,
    "bot_protection": null,
    "captcha": null,
    "ios_link_destination": null,
    "name": null,
     "tags": [
        {
          "created_at": "2023-09-11_02-33-06",
          "id": 2,
          "name": "Tag 2",
          "organization_id": 1
        }
    ],
    "password": null,
    "webhook_auth_key": null,
    "webhook_url": null,
    "zapier_key": "a5U8OaWIkViD741bFRiFKUPidhnqWudv_egsIKRWk4w",
    "zapier_webhook_url_new_click": null
}

DELETE/api/v1/link/<id>

Delete a short link

Required Attributes

Name
id
Type
string
Description
The ID of the link as returned by the y.gy API originally

Response

The response is a 204 Status code.