short

Short API Endpoint: Shorten links using Ayrshare's URL link shortener.

Link Shortener API Endpoint

Please try the new link shortener endpoint. The link shortener we use for this /short endpoint is being deprecated by Google and will no longer be available after June 3, 2024. We recommend using the new /links endpoint since it has no external dependencies and greater functionality.

The /short endpoint can be used as a URL link shortener API. POST a URL, such as a website, to the endpoint and a shortened link is returned. URLs in the post body of the /post endpoint are automatically shortened and can be disabled with shortenLinks=false parameter.

A URL shortener reduces the size of a URL to make it more readable, saves characters, which is especially important for social networks such as Twitter, and allows analytics tracking of impressions and clicks. Shortened links use the ayr.app domain.

A custom URL shortener, known as a branded URL shortener, is available for Enterprise Plans.

Premium or Business Plan required.

❗Click the › in the endpoint to view details.

---

POST Shorten a URL

POST https://app.ayrshare.com/api/short

URL Shortener. Submit a URL and get a shortened URL to save characters. This is helpful when you want to conserve your character count on Twitter. Note: in the /post endpoint you automatically shorten URLs in the post text. Note: url must begin with https:// Premium or Business Plan required.

Headers

Name	Type	Description
Authorization*	string	Format: Authorization: Bearer API_KEY. See Overview for more information.
Profile-Key	string	The Profile Key of a user profile.

Request Body

Name	Type	Description
url*	string	URL to be shortened. Must be a valid URL starting with "https://"
socialMeta	object	Please see below

200 Return of the shortened URL

{
    "status": "success",
    "shortUrl": "https://ayr.app/l/hXcC",
    "originalUrl": "https://www.google.com"
}

Request Examples

cURL

curl \
-H "Authorization: Bearer API_KEY" \
-H 'Content-Type: application/json' \
-d '{"url": "https://www.ayrshare.com"}' \
-X POST https://app.ayrshare.com/api/shorten

Node.js

const API_KEY = "API_KEY";
const url = "https://www.ayrshare.com";

fetch("https://app.ayrshare.com/api/shorten", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${API_KEY}`
      },
      body: JSON.stringify({ url }),
    })
      .then((res) => res.json())
      .then((json) => console.log(json))
      .catch(console.error);

Python

import requests

payload = {'url': 'https://www.ayrshare.com'}
headers = {'Content-Type': 'application/json', 
        'Authorization': 'Bearer API_KEY'}

r = requests.post('https://app.ayrshare.com/api/shorten', 
    json=payload, 
    headers=headers)
    
print(r.json())

PHP

<?php
require 'vendor/autoload.php';    // Composer auto-loader using Guzzle. See https://docs.guzzlephp.org/en/stable/overview.html

$client = new GuzzleHttp\Client();
$res = $client->request(
    'POST',
    'https://app.ayrshare.com/api/shorten',
    [
        'headers' => [
            'Content-Type'      => 'application/json',
            'Authorization'     => 'Bearer API_KEY'
        ],
        'json' => [
            'url' => ['https://www.ayrshare.com'],
        ]
    ]
);

echo json_encode(json_decode($res->getBody()), JSON_PRETTY_PRINT);

Social Media Link Preview

When creating the shortened URL, you may also specify social media metadata for the link preview. The title, description, and image can be set. For example:

Link Preview Metadata

The above Tweet preview link was created with the following:

{
    "url": "https://www.ayrshare.com",
    "socialMeta": {
        "title": "Social Media with an API",
        "description": "Social done right with an API. The only way to go!",
        "mediaUrl": "https://img.ayrshare.com/012/gb.jpg"
    }
}

All fields are required or the metadata will not be set.

• title: The preview title.

• description: Body description of the preview.

• mediaUrl: URL to the image used by the preview. The image should be at least 300x200 px, and less than 300 KB.

Social metadata is passed to Twitter, Facebook, Facebook Messenger, iMessage, WhatsApp, and other services.

Bitly Integration

You may use your own link shortener, such as Bit.ly, by providing us with the API key from the link shortening service. This allows you to use a custom domain when shortening the link. You may then directly call the bit.ly API to retrieve analytics. Please contact us for more information.

Available for Premium and Business Plans

---

GET Analytics on a Shortened Link

GET https://app.ayrshare.com/api/analytics/links

Get shortened link analytics. Note, click counts could take up to an hour to reflect in the analytics data. Premium or Business Plan required.

Query Parameters

Name	Type	Description
lastDays	number	Get history of links posted over the past n days. Range 1-90 days. Default: 1 day.

Headers

Name	Type	Description
Authorization*	string	Format: Authorization: Bearer API_KEY. See Overview for more information.
Profile-Key	string	Profile Key of a user profile.

200: Success

[
    {
        "linkEventStats": [
            {
                "count": "6",
                "event": "CLICK",
                "platform": "OTHER"
            },
            {
                "count": "1",
                "event": "CLICK",
                "platform": "IOS"
            }
        ],
        "link": "https://bookriot.com/book-riots-deals-of-the-day-for-september-27-2020/",
        "shortLink": "https://ayr.app/l/Nz3L",
        "created": {
            "_seconds": 1601215211,
            "_nanoseconds": 413000000
        },
        "clicks": 7        // Total click across platforms
    },
    {
        "linkEventStats": [
            {
                "count": "11",
                "event": "CLICK",
                "platform": "OTHER"
            },
            {
                "count": "2",
                "event": "CLICK",
                "platform": "IOS"
            }
        ],
        "link": "https://neilpatel.com/blog/reputation-management-agency/",
        "shortLink": "https://ayr.app/l/TSdN",
        "created": {
            "_seconds": 1601223003,
            "_nanoseconds": 7000000
        },
        "clicks": 13        // Total click across platforms
    }
]

400: Error

{
    "action": "analytics",
    "status": "error",
    "code": 186,
    "message": "Post ID not found.",
    "id": "IHvCmacgIc6hMU9IQ6C"
}

Request Examples

cURL

Node.js

const API_KEY = "API_KEY";
const lastDays = 2;

fetch(`https://app.ayrshare.com/api/analytics/links?lastDays=${lastDays}`, {
      method: "GET",
      headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${API_KEY}`
      }
    })
      .then((res) => res.json())
      .then((json) => console.log(json))
      .catch(console.error);

Python

import requests

headers = {'Content-Type': 'application/json', 
        'Authorization': 'Bearer API_KEY'}

r = requests.delete('https://app.ayrshare.com/api/analytics/links?lastDays=2', 
    headers=headers)
    
print(r.json())

PHP

<?php

$lastdays = "2";
$apiUrl = 'https://app.ayrshare.com/api/analytics/links?lastDays=' . $lastdays;
$apiKey = 'API_KEY';  // Replace 'API_KEY' with your actual API key

$headers = [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $apiKey,
];

$curl = curl_init($apiUrl);
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => $headers
]);

$response = curl_exec($curl);

if ($response === false) {
    echo 'Curl error: ' . curl_error($curl);
} else {
    echo json_encode(json_decode($response), JSON_PRETTY_PRINT);
}

curl_close($curl);

C#

using System;
using System.Net;
using System.IO;

namespace LinksGETRequest_charp
{
    class Links
    {
        static void Main(string[] args)
        {
            string API_KEY = "API_KEY";
            string url = "https://app.ayrshare.com/api/analytics/links";

            var httpWebRequest = WebRequest.CreateHttp(url);
            httpWebRequest.ContentType = "application/json";
            httpWebRequest.Headers.Add("Authorization", "Bearer " + API_KEY);

            var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
            using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
            {
                var response = streamReader.ReadToEnd();
                Console.WriteLine(response);
            }
        }
    }
}