Link API | How to Shorten Links using the Y.GY API
This is the main API to create new short links with y.gy.
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 likey.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
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 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
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 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
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 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
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 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.