API

Registering for an API Key

An API key is required for requests to be processed by the system. Once a user registers, an API key is automatically generated for this user. Please login and go to your Settings page to retrieve your account API key. The API key must attached to the request via the api parameter (see full example below).


Sending a request for generating a tweetable URL

To send a request, the user must use the following format where the variables api and tweetable are required. Optional parameters are &via= to add a via @account, &related= to add a related @account and &link= to add a link to the end of the tweet.

  GET https://tweetable.link/api?api=APIKEY&tweetable=YOUR%20TWEET%20TEXT&via=tweetablelink&related=johndoe&link=example.com

Server response

The response will be encoded in JSON format (default). This is done to facilitate cross-language usage. The first element of the response will always tell if an error has occurred (error: 1) or not (error: 0). The second element will change with respect to the first element. If there is an error, the second element will be named “msg”. which contains the source of error. (See below for an example)

// No errors
{
  "error":0,
  "short":"http://twt.li/8kiBc"
}
// An error has occurred
{
  "error":1,
  "msg":"Please enter some text."
}

Using plain text format

You can now request the response to be in plain text by just adding &format=text at the end of your request. This will return just http://twt.li/8kiBc instead of the JSON response. Note that if an error occurs, it will not output anything.


Sending a request for shortening a URL

To send a request, the user must use the following format where the variables api and url are required. To request a custom alias, simply add &custom= at the end.

  GET https://tweetable.link/api?api=APIKEY&url=THELONGURLTOBESHORTENED&custom=CUSTOMALIAS

Server response

As before, the response will be encoded in JSON format (default). This is done to facilitate cross-language usage. The first element of the response will always tell if an error has occurred (error: 1) or not (error: 0). The second element will change with respect to the first element. If there is an error, the second element will be named “msg”. which contains the source of error, otherwise it will be named “short” which contains the short URL. (See below for an example)

// No errors
{
  "error":0,
  "short":"http://twt.li/PvZ2s"
}
// An error has occurred
{
  "error":1,
  "msg":"Please enter a valid URL"
}

Using plain text format

You can now request the response to be in plain text by just adding &format=text at the end of your request. This will return just http://twt.li/PvZ2s instead of the JSON response. Note that if an error occurs, it will not output anything.


Sending a request for info about a short URL

To send a request, the user must use the following format where the variables api and short are required.

  GET https://tweetable.link/api?api=APIKEY&short=URLSHORTCODEORALIAS

Server response

As before, the response will be encoded in JSON format (default). This is done to facilitate cross-language usage. The first element of the response will always tell if an error has occurred (error: 1) or not (error: 0). The second element will change with respect to the first element. If there is an error, the second element will be named “msg”. which contains the source of error. (See below for an example)

// No errors
{
  "error":0,
  "long":"http://thelongdestinationurl.com",
  "click":"12",
  "date":"2014-07-26 14:056:58",
  "location":
    {
      "Belgium":"http://anotherurl.com"
    }
}
// An error has occurred
{
  "error":1,
  "msg":"This URL couldn\'t be found. Please double check it."
}

Using plain text format

You can now request the response to be in plain text by just adding &format=text at the end of your request. This will return just http://thelongdestinationurl.com instead of the JSON response. Note that if an error occurs, it will not output anything.