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

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>
  • 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

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>

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>

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.