Developer Hub

REST API Documentation & Guide

Programmatically create short links, customize branded slugs, query click analytics, and manage link collections in real-time.

Step 1: Generate & Manage Your API Key

To access the REST API, sign in to your account and go to Customer Dashboard → REST API Keys to generate a secret token.

Supported Authentication Methods:
You can authenticate your HTTP requests using any of the 3 standard headers/parameters below:

Authorization: Bearer YOUR_API_KEY (Recommended)
X-API-KEY: YOUR_API_KEY
https://freeurlshort.com/api/v1/links?api_key=YOUR_API_KEY

Short Link Target Domain Selection:
When creating short links via the API, short URLs are automatically generated using the Short Link Domain configured for your API key in your Customer Dashboard. You can easily switch or update the default domain for any API key in your dashboard, or override it dynamically by passing a domain field in your JSON API request payload.

Authorization: Bearer 7|cN85X2R5vqGwJb00IiYcbg2hlfXrt0QONL3NNNEqb0d7e644

POST

Create Short URL

https://freeurlshort.com/api/v1/shorten

Request Body (JSON):

Parameter	Type	Required	Description
`original_url`	String (URL)	Required	The long URL to shorten (must start with `http://` or `https://`).
`domain`	String	Optional	Selected shortener domain (e.g. `freeurlshort.com`). Defaults to your API key's configured domain.
`title`	String	Optional	A custom descriptive title for link organization.
`custom_alias`	String	Optional	Custom slug (e.g. `my-promo-2026`).
`password`	String	Optional	Set a password requirement to protect the short link.
`redirect_type`	Integer	Optional	HTTP redirect status code: `301` (Permanent), `302` (Temporary), or `307`.
`max_clicks`	Integer	Optional	Maximum allowed clicks before auto-expiry.
`expires_at`	DateTime	Optional	Expiration date timestamp (e.g. `2026-12-31 23:59:59`).

curl -X POST "https://freeurlshort.com/api/v1/shorten" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "original_url": "https://example.com/target-landing-page",
    "title": "Summer Campaign Link",
    "custom_alias": "promo-2026"
  }'

<?php
$apiKey = "YOUR_API_KEY";
$url = "https://freeurlshort.com/api/v1/shorten";

$data = [
    "original_url" => "https://example.com/target-landing-page",
    "title" => "Summer Campaign Link",
    "custom_alias" => "promo-2026"
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {$apiKey}",
        "Content-Type: application/json",
        "Accept: application/json"
    ]
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
?>

const apiKey = "YOUR_API_KEY";

fetch("https://freeurlshort.com/api/v1/shorten", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  body: JSON.stringify({
    original_url: "https://example.com/target-landing-page",
    title: "Summer Campaign Link",
    custom_alias: "promo-2026"
  })
})
.then(response => response.json())
.then(data => console.log("Short URL created:", data.data.short_url))
.catch(error => console.error("Error:", error));

import requests

api_key = "YOUR_API_KEY"
url = "https://freeurlshort.com/api/v1/shorten"

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
    "Accept": "application/json"
}

payload = {
    "original_url": "https://example.com/target-landing-page",
    "title": "Summer Campaign Link",
    "custom_alias": "promo-2026"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Example Success Response (201 Created):

{
  "success": true,
  "message": "Short URL created successfully.",
  "data": {
    "id": 42,
    "title": "Summer Campaign Link",
    "short_code": "promo-2026",
    "short_url": "https://freeurlshort.com/promo-2026",
    "original_url": "https://example.com/target-landing-page",
    "qr_code_url": "https://freeurlshort.com/dashboard/qr?link_id=42",
    "clicks_count": 0,
    "is_active": true,
    "created_at": "2026-08-18T20:34:05+00:00"
  }
}

GET

List My Links

https://freeurlshort.com/api/v1/links

Retrieve a paginated list of all shortened links under your account.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://freeurlshort.com/api/v1/links?page=1"

GET

Link Analytics

https://freeurlshort.com/api/v1/links/{id}/analytics

Fetch total clicks, top countries, browsers, and device platforms for a link.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://freeurlshort.com/api/v1/links/42/analytics"

GET

Get Link Details

https://freeurlshort.com/api/v1/links/{id}

Retrieve full configuration and click statistics for a specific short code or ID.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://freeurlshort.com/api/v1/links/42"

DELETE

Delete Short URL

https://freeurlshort.com/api/v1/links/{id}

Permanently delete a short link by its numeric ID or custom slug.

curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://freeurlshort.com/api/v1/links/42"