Developer Hub

REST API Documentation & Guide

Programmatically create short links, customize branded slugs, query click analytics, and manage link collections in real-time. Follow our Step-by-Step API Tutorial, inspect our live System Status, or explore All Platform Features.

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.

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-10-11T12:47:57+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"

Rate Limiting & HTTP Response Headers

All FreeURLShort API endpoints are protected by intelligent rate-limiting algorithms to maintain high availability across all accounts. Every HTTP response returns standard headers following IETF RFC 7231 and OpenAPI 3.0 specifications:

Header Description Example
X-RateLimit-Limit The maximum number of allowed requests in the current time window. 60
X-RateLimit-Remaining The remaining number of allowed requests in the current window. 54
Retry-After Sent only on HTTP 429 responses, indicating seconds until rate limit resets. 30
Standard HTTP Status Codes
Status Code Status Name Condition / Meaning
200 OK Success The request was successful and data payload is returned.
201 Created Created The short URL or resource was created successfully.
400 Bad Request Malformed Request Invalid JSON body or missing required attributes.
401 Unauthorized Authentication Failed Missing or invalid API key / Bearer token.
403 Forbidden Forbidden Your account plan does not have permission for the requested resource.
404 Not Found Not Found The requested link ID or slug does not exist or has been deleted.
422 Unprocessable Validation Error The destination URL is invalid or custom alias is already taken.
429 Too Many Requests Rate Limit Exceeded You have sent too many requests in a given time window.