# 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! :)