API Documentation

Everything you need to integrate blx.ist into your project.

Base URL

https://blx.ist

Authentication

All API requests require an Authorization header with your API token.

Authorization: your_api_token_here

Don't have a token? Get one for free.

Endpoints

POST /api/shorten

Create a shortened URL.

Headers

Name Required Description
Authorization Required Your API token

Body Parameters

Name Type Required Description
url string Required A valid URL to shorten

Error Codes

Status Message
401 Missing authorization token
401 Invalid token
401 Missing url
401 Url is not valid
GET /api/urls

List the short URLs created with your token, newest first. Returns only URLs that belong to your account.

Headers

Name Required Description
Authorization Required Your API token

Query Parameters

Name Type Description
search string Filter by original URL or short code.
page integer Page number. Default 1.
per_page integer Results per page. Default 50, max 100.

Example Response

{
  "status": "success",
  "data": [
    {
      "short_link": "https://blx.ist/abcde",
      "url": "https://example.com/long-url",
      "clicks": 142,
      "last_clicked_at": "2026-06-08T10:30:00+00:00",
      "created_at": "2026-05-01T09:00:00+00:00"
    }
  ],
  "page": 1,
  "per_page": 50,
  "total": 12
}

Error Codes

Status Message
401 Missing authorization token / Invalid token
GET /api/urls/{short_url}/stats

Get click analytics for one of your short URLs: total clicks, period breakdowns, and a paginated list of recent click details. You can only access URLs that belong to your account.

Headers

Name Required Description
Authorization Required Your API token

Query Parameters

Name Type Description
page integer Page of click details to return. Default 1.
per_page integer Click details per page. Default 50, max 100.

Example Response

{
  "status": "success",
  "short_link": "https://blx.ist/abcde",
  "url": "https://example.com/long-url",
  "total_clicks": 142,
  "last_clicked_at": "2026-06-08T10:30:00+00:00",
  "periods": { "today": 5, "yesterday": 3, "week": 21, "month": 142 },
  "clicks": {
    "data": [
      {
        "ip": "88.240.x.x",
        "device": "Mobile",
        "browser": "Chrome",
        "platform": "Android",
        "referer": "https://twitter.com",
        "clicked_at": "2026-06-08T10:30:00+00:00"
      }
    ],
    "page": 1,
    "per_page": 50,
    "total": 142
  }
}

For visitor privacy, IP addresses are masked (e.g. 88.240.x.x) — the full address is never exposed through the API.

Error Codes

Status Message
401 Missing authorization token / Invalid token
403 You do not have access to this URL
404 URL not found
GET /api/stats

Get an account-wide summary across all your short URLs: total number of URLs, total clicks, and your top 10 most-clicked links.

Headers

Name Required Description
Authorization Required Your API token

Example Response

{
  "status": "success",
  "total_urls": 12,
  "total_clicks": 350,
  "top_urls": [
    {
      "short_link": "https://blx.ist/abcde",
      "url": "https://example.com/long-url",
      "clicks": 142,
      "last_clicked_at": "2026-06-08T10:30:00+00:00"
    }
  ]
}

Error Codes

Status Message
401 Missing authorization token / Invalid token

Code Examples

cURL 
curl -X POST https://blx.ist/api/shorten \
  -H "Authorization: YOUR_API_KEY_HERE" \
  -F "url=https://example.com"
PHP 
$ch = curl_init('https://blx.ist/api/shorten');
curl_setopt_array($ch, [
  CURLOPT_POST           => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER     => ['Authorization: YOUR_API_KEY_HERE'],
  CURLOPT_POSTFIELDS     => ['url' => 'https://example.com'],
]);
$response = json_decode(curl_exec($ch));
curl_close($ch);
echo $response->short_url;
Node.js 
const form = new FormData();
form.append('url', 'https://example.com');

const res = await fetch('https://blx.ist/api/shorten', {
  method: 'POST',
  headers: { 'Authorization': 'YOUR_API_KEY_HERE' },
  body: form,
});
const data = await res.json();
console.log(data.short_url);
Python 
import requests

r = requests.post('https://blx.ist/api/shorten',
    headers={'Authorization': 'YOUR_API_KEY_HERE'},
    data={'url': 'https://example.com'})
print(r.json()['short_url'])
Success Response 
{
  "status": "success",
  "url": "https://example.com",
  "short_url": "https://blx.ist/a4f2c"
}
Error Response 
{
  "status": "error",
  "message": "Invalid token"
}