---
# System prepended metadata

title: Links short Bot ENDPOINTS

---

# Links short Bot ENDPOINTS

These are the endpoints you can use to short links with [@LinksShortBot](#http://t.me/LinksShortBot) on Telegram

## Info

All replies are in JSON.

🌎 Endpoint URL: https://s.tranck.ovh/api/

⚠️⚠️ **PUT THE [Auth-Header](#Auth-Header) IN EVERY REQUEST TO OUR ENDPOINTS!** ⚠️⚠️

# Index
* [Info](#Info)
* [Index](#Index)
* [Objects](#Objects)
  * [Error](#Error)
* [Endpoints](#Endpoints)
	* [shortLink](#shortLink)
	* [deleteLink](#deleteLink)
	* [editLink](#editLink)
	* [getClicks](#getClicks)
	* [getFullStats](#getFullStats)
	* [getUserInfo](#getUserInfo)
	* [getOriginalLink](#getOriginalLink)
	* [ping](#ping)
* [Extra](#Extra)
	* [Auth-header](#Auth-header)
	* [Domains](#Domains)

# Objects

## Error
🍁 **Returned object if any error occurs**

| Param   | Type    | Description                 |
| ------- |:------- |:--------------------------- |
| error   | boolean | `true` if an error occurred |
| message | String  | Message of the error      |

There are some generic errors related to missing/bad parameters. And some specific ones (like 404s). These are specified in the description of each endpoint


# Endpoints

## shortLink
🦧🦧 **Shorts a new link** 🦧🦧

⚠️ The same user can short the same link only with a 10 minutes interval. If you try to short the same link before 10 minutes, you'll get the same `shortCode` as before. Use the `forceShort` parameter if you want a new shorted link anyway.

⬇️ GET
### 😳 Params:

| Param      | Type    | Required | Description                                                                                                                                                                                 |
| ---------- | ------- | -------- |:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| link       | String  | yes      | URL-Encoded link you wanna short                                                                                                                                                            |
| forceShort | boolean | no       | Set this to `true` if you want to ALWAYS get a new shortedLink, even if you just created another shorted link from the same expanded link. Plz use this only when it's strictly necessary 🙏 |

### ✅ Return:

| Param     | Type    | Description                                                                                   |
| --------- |:------- |:--------------------------------------------------------------------------------------------- |
| error     | boolean | `true` if an error occurred. In that case, this object will be a [Error](#Error)              |
| shortCode | String  | The URI path you should append to the short domain you want to use. Check [Domains](#Domains) |

📉 Possible errors:
* 402 Daily quota exceeded!
* 405 Invalid param(s): 'link'


## deleteLink
🦧🦧 **Delete a link you have previously shorted** 🦧🦧
⬇️ GET
### 😳 Params:

| Param     | Type   | Required | Description                                                            |
| --------- | ------ | -------- |:---------------------------------------------------------------------- |
| shortCode | String | yes      | The path part of the shorten URI (Returned by [shortLink](#shortLink)) |

### ✅ Return:

| Param | Type    | Description                                                                      |
| ----- |:------- |:-------------------------------------------------------------------------------- |
| error | boolean | `true` if an error occurred. In that case, this object will be a [Error](#Error) |

📉 Possible errors:
* 404 Shorted link not found

## editLink
🦧🦧 **Edit the redirect of a link you have previously shorted** 🦧🦧
⬇️ GET
### 😳 Params:

| Param     | Type   | Required | Description                                                                           |
| --------- | ------ | -------- |:------------------------------------------------------------------------------------- |
| shortCode | String | yes      | The path part of the shorten URI (Returned by [shortLink](#shortLink))                |
| link      | String | yes      | The new URL-Encoded link where users will be redirected when opening the shorted link |

### ✅ Return:

| Param | Type    | Description                                                                      |
| ----- |:------- |:-------------------------------------------------------------------------------- |
| error | boolean | `true` if an error occurred. In that case, this object will be a [Error](#Error) |

📉 Possible errors:
* 404 Shorted link not found

## getOriginalLink
🦧🦧 **Returns the original expanded link from a shortcode or a shorted link** 🦧🦧
⬇️ GET
### 😳 Params:

| Param     | Type   | Required | Description                                                                                     |
| --------- | ------ | -------- |:----------------------------------------------------------------------------------------------- |
| shortCode | String | yes      | The path part of the shorten URI (Returned by [shortLink](#shortLink)) or the full shorted link |

### ✅ Return:

| Param    | Type    | Description                                                                      |
| -------- |:------- |:-------------------------------------------------------------------------------- |
| error    | boolean | `true` if an error occurred. In that case, this object will be a [Error](#Error) |
| fullLink | String  | The original link where the `shortCode` redirects to                             |

📉 Possible errors:
* 404 Shorted link not found

## getClicks
🦧🦧 **Gets the number of visits to a specified short link** 🦧🦧

⚠️ The number of clicks is cached up to 10 minutes from the first request! Check the `ignoreCache` parameter

⬇️ GET
### 😳 Params:

| Param       | Type    | Required | Description                                                                                                               |
| ----------- | ------- |:-------- |:------------------------------------------------------------------------------------------------------------------------- |
| shortCode   | String  | yes      | The path part of the shorten URI (Returned by [shortLink](#shortLink))                                                    |
| ignoreCache | boolean | no       | Set this to `true` to ignore the 10 mins cache on the return parameter. Plz use this only when it's strictly necessary 🙏 |

### ✅ Return:

| Param  | Type    | Description                                                                      |
| ------ |:------- |:-------------------------------------------------------------------------------- |
| error  | boolean | `true` if an error occurred. In that case, this object will be a [Error](#Error) |
| clicks | int     | Number of visits to that link                                                    |

📉 Possible errors:
* 404 Shorted link not found

## getFullStats
🦧🦧 **Gets the full list of visits to a specified short link** 🦧🦧

⚠️ The CSV returned is cached up to 10 minutes from the first request! Check the `ignoreCache` parameter

⬇️ GET
### 😳 Params:

| Param       | Type    | Required | Description                                                                                                               |
| ----------- | ------- |:-------- |:------------------------------------------------------------------------------------------------------------------------- |
| shortCode   | String  | yes      | The path part of the shorten URI (Returned by [shortLink](#shortLink))                                                    |
| ignoreCache | boolean | no       | Set this to `true` to ignore the 10 mins cache on the return parameter. Plz use this only when it's strictly necessary 🙏 |


### ✅ Return:

An [Error](#Error) object if any problems occurred, otherwise a csv **(NOT A JSON!)** containing the full list of visits to that link containing the following fields. (Note: the CSV starts with it's own header)
| Param       | Type   | Description                                                                                                       |
| ----------- |:------ |:----------------------------------------------------------------------------------------------------------------- |
| timestamp   | long   | unix timestamp (GMT + 0) when the visit occurred                                                                  |
| year        | int    | year (GMT + 0) when the visit occurred                                                                            |
| month       | int    | month (GMT + 0) when the visit occurred _(January = 0)_                                                           |
| day         | int    | day (GMT + 0) when the visit occurred _(1st of a month = 1)_                                                      |
| day-of-week | int    | number of the day inside the week (GMT + 0) when the visit occurred _(sunday = 1, monday = 2, ..., saturday = 7)_ |
| hour        | int    | hour (GMT + 0) when the visit occurred _(0-23h)_                                                                  |
| minute      | int    | minute (GMT + 0) when the visit occurred _(0-59m)_                                                                |
| ip          | String | The MD5 hashed ip where the visit is made. You can use this to check unique visits                                |
| language    | String | Content of the HTTP header `Accept-Language` from the request made in this visit                                  |
| userAgent   | String | Content of the HTTP header `User-Agent` from the request made in this visit                                       |
| language    | String | Content of the HTTP header `Referer ` from the request made in this visit                                         |
📉 Possible errors:
* 404 Shorted link not found


## getUserInfo
🦧🦧 **Returns the info associated with your api token** 🦧🦧
⬇️ GET

### ✅ Return:

| Param        | Type    | Description                                                                      |
| ------------ |:------- |:-------------------------------------------------------------------------------- |
| error        | boolean | `true` if an error occurred. In that case, this object will be a [Error](#Error) |
| userId       | long    | Your telegram userID                                                             |
| shortedToday | int     | Number of links you have shorted today                                           |
| maxShorts    | int     | Max number of links you can short per day                                        |

## ping
🦧🦧 **Ping!** 🦧🦧
⬇️ GET
### 😳 Params:

![](https://i.imgur.com/kKOk41K.png)


### ✅ Return:

Pong!

# Extra

## Auth-header

🍆 If you want to use our APIs, you need to authenticate every request to this endpoint with your private token. You can find it onto our [Telegram bot](#http://t.me/LinksShortBot).

`X-stranckShortner-token: <your API token>`

## Domains

🍆 You can use this shortner service with whatever domain you want!

Just include in your DNS configurations `<domain> CNAME s.tranck.ovh`, or use a reverse proxy to `s.tranck.ovh`. This shortner will always use filename part of the URI, so you can even put a path before the  `shortCode` (EG: `short.example.com/path/to/shortner/SHORTPATH`)

The `shortCode` value returned by [shortLink](#shortLink) will contain the URI path you should append to your domain. If your domain is `short.example.com` and the returned `shortCode` value is `ABC123`, your final url will be `short.example.com/ABC123`.

⚠️ **Important note!**
We currently accept requests only through http ports 80, 8080 and https port 443
You can register up to 100 subdomains per registered domain. We use the [Public Suffix List](https://publicsuffix.org/) to calculate the registered domain.

✅ **If you don't have any custom domains available**, you can use our personal domain `s.stranck.ovh` without problems! :)