URL Shortener API

Powerful REST API for programmatic link management

Introduction

Welcome to the URL Shortener API! Our RESTful API allows you to create, manage, and track shortened URLs programmatically. Perfect for developers who want to integrate link shortening into their applications.

Base URL: https://ts4.in/api/v1

Authentication

All API requests require authentication using an API key. You can obtain your API key from your dashboard.

Using Your API Key

Include your API key in the request header:

X-API-Key: sk_your_api_key_here

Alternatively, you can pass it as a query parameter:

?api_key=sk_your_api_key_here

Rate Limiting

API requests are rate-limited based on your API key configuration. Default limit is 1000 requests per hour.

If you exceed your rate limit, you'll receive a 429 Too Many Requests response.

Response Headers

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per hour
`X-RateLimit-Remaining`	Remaining requests in current window

API Endpoints

GET /api/v1/shortlinks

Retrieve a paginated list of your shortened URLs.

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (default: 20, max: 100)
`search`	string	Search by URL or title
`sort_by`	string	Sort field: created_at, clicks (default: created_at)
`sort_order`	string	asc or desc (default: desc)

Example Request

curl -X GET "https://ts4.in/api/v1/shortlinks?page=1&per_page=20" \
  -H "X-API-Key: sk_your_api_key_here"
                    

Example Response

{
  "success": true,
  "data": [
    {
      "id": 1,
      "original_url": "https://example.com/long-url",
      "short_code": "abc123",
      "short_url": "https://ts4.in/abc123",
      "title": "Example Link",
      "description": "This is an example",
      "clicks": 42,
      "created_at": "2025-01-13T12:00:00.000000Z",
      "expires_at": null
    }
  ],
  "meta": {
    "current_page": 1,
    "total": 100,
    "per_page": 20,
    "last_page": 5
  }
}
                    

POST /api/v1/shortlinks

Create a new shortened URL.

Request Body

Parameter	Type	Required	Description
`url`	string	Yes	The URL to shorten
`custom_alias`	string	No	Custom short code (6-20 characters)
`title`	string	No	Title for the link
`description`	string	No	Description of the link
`expires_at`	datetime	No	Expiration date (ISO 8601 format)
`password`	string	No	Password protect the link

Example Request

curl -X POST "https://ts4.in/api/v1/shortlinks" \
  -H "X-API-Key: sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/my-long-url",
    "custom_alias": "mylink",
    "title": "My Example Link",
    "description": "This is a test link"
  }'
                    

Example Response

{
  "success": true,
  "data": {
    "id": 123,
    "original_url": "https://example.com/my-long-url",
    "short_code": "mylink",
    "short_url": "https://ts4.in/mylink",
    "title": "My Example Link",
    "description": "This is a test link",
    "clicks": 0,
    "created_at": "2025-01-13T12:00:00.000000Z"
  }
}
                    

GET /api/v1/shortlinks/{id}

Retrieve details of a specific shortened URL.

Example Request

curl -X GET "https://ts4.in/api/v1/shortlinks/123" \
  -H "X-API-Key: sk_your_api_key_here"
                    

PUT /api/v1/shortlinks/{id}

Update an existing shortened URL. You can update title, description, expiration, and other metadata.

Example Request

curl -X PUT "https://ts4.in/api/v1/shortlinks/123" \
  -H "X-API-Key: sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Title",
    "description": "Updated description"
  }'
                    

DELETE /api/v1/shortlinks/{id}

Delete a shortened URL permanently.

Example Request

curl -X DELETE "https://ts4.in/api/v1/shortlinks/123" \
  -H "X-API-Key: sk_your_api_key_here"
                    

GET /api/v1/shortlinks/{id}/analytics

Get detailed analytics for a specific shortened URL including clicks by date, country, browser, OS, and device type.

Example Request

curl -X GET "https://ts4.in/api/v1/shortlinks/123/analytics" \
  -H "X-API-Key: sk_your_api_key_here"
                    

Example Response

{
  "success": true,
  "data": {
    "total_clicks": 152,
    "clicks_by_date": {
      "2025-01-12": 45,
      "2025-01-13": 107
    },
    "clicks_by_country": {
      "US": 89,
      "UK": 33,
      "CA": 30
    },
    "clicks_by_browser": {
      "Chrome": 98,
      "Firefox": 32,
      "Safari": 22
    }
  }
}
                    

POST /api/v1/shortlinks/bulk

Create multiple shortened URLs in a single request (up to 100 URLs).

Request Body

curl -X POST "https://ts4.in/api/v1/shortlinks/bulk" \
  -H "X-API-Key: sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      {
        "url": "https://example.com/page1",
        "title": "Page 1"
      },
      {
        "url": "https://example.com/page2",
        "title": "Page 2"
      }
    ]
  }'
                    

Error Handling

All error responses follow a consistent format:

{
  "success": false,
  "message": "Error description",
  "errors": {
    "field": ["Validation error message"]
  }
}
                

HTTP Status Codes

Code	Description
`200`	Success
`201`	Created
`400`	Bad Request
`401`	Unauthorized (missing or invalid API key)
`403`	Forbidden (insufficient permissions)
`404`	Not Found
`429`	Too Many Requests (rate limit exceeded)
`500`	Internal Server Error

Code Examples

PHP

<?php
$apiKey = 'sk_your_api_key_here';
$baseUrl = 'https://ts4.in/api/v1';

$ch = curl_init($baseUrl . '/shortlinks');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: ' . $apiKey,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'url' => 'https://example.com/long-url',
    'title' => 'My Link'
]));

$response = curl_exec($ch);
$data = json_decode($response, true);

echo $data['data']['short_url'];
?>
                

JavaScript (Node.js)

const axios = require('axios');

const apiKey = 'sk_your_api_key_here';
const baseUrl = 'https://ts4.in/api/v1';

async function createShortlink() {
  const response = await axios.post(`${baseUrl}/shortlinks`, {
    url: 'https://example.com/long-url',
    title: 'My Link'
  }, {
    headers: {
      'X-API-Key': apiKey,
      'Content-Type': 'application/json'
    }
  });
  
  console.log(response.data.data.short_url);
}

createShortlink();
                

Python

import requests

api_key = 'sk_your_api_key_here'
base_url = 'https://ts4.in/api/v1'

headers = {
    'X-API-Key': api_key,
    'Content-Type': 'application/json'
}

data = {
    'url': 'https://example.com/long-url',
    'title': 'My Link'
}

response = requests.post(f'{base_url}/shortlinks', 
                        json=data, 
                        headers=headers)
result = response.json()

print(result['data']['short_url'])
                

Ready to get started?

Create your API key and start integrating today!

Get Your API Key