URLVanish API Documentation

Introduction

Welcome to the URLVanish API! Our REST API allows you to integrate URL shortening capabilities directly into your applications. Create, manage, and track shortened URLs programmatically while maintaining the same privacy-focused approach that makes URLVanish unique.

Authentication

URLVanish API uses simple API key authentication. To get started:

1. Create an account at URLVanish
2. Generate your API key from your dashboard
3. Include your API key in the request header

Authentication Header

Authorization: Bearer YOUR_API_KEY

Rate Limits

To ensure fair usage for all users, we implement the following rate limits:

• Free users: 100 requests per hour
• Registered users: 1,000 requests per hour
• Premium users: 10,000 requests per hour

API Endpoints

All API endpoints use the base URL: https://urlvanish.com/api/

Create Short URL

Creates a new shortened URL.

Request Body

Parameter	Type	Required	Description
url	string	Yes	The URL to shorten
alias	string	No	Custom alias for the short URL
expires	datetime	No	Expiration date (ISO 8601 format)

Example Request

{
  "url": "https://example.com/very-long-url",
  "alias": "my-custom-link",
  "expires": "2024-12-31T23:59:59Z"
}

Example Response

{
  "success": true,
  "data": {
    "id": "abc123",
    "short_url": "https://urlvanish.com/my-custom-link",
    "original_url": "https://example.com/very-long-url",
    "alias": "my-custom-link",
    "created_at": "2024-01-15T10:30:00Z",
    "expires_at": "2024-12-31T23:59:59Z",
    "click_count": 0
  }
}

Get URL Information

Retrieves information about a shortened URL.

Example Response

{
  "success": true,
  "data": {
    "id": "abc123",
    "short_url": "https://urlvanish.com/my-custom-link",
    "original_url": "https://example.com/very-long-url",
    "alias": "my-custom-link",
    "created_at": "2024-01-15T10:30:00Z",
    "expires_at": "2024-12-31T23:59:59Z",
    "click_count": 42,
    "last_clicked": "2024-01-20T14:22:00Z"
  }
}

Delete URL

Deletes a shortened URL. This action cannot be undone.

Example Response

{
  "success": true,
  "message": "URL deleted successfully"
}

List URLs

Lists all URLs created by the authenticated user.

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	50	Results per page (max 100)
sort	string	created_at	Sort field (created_at, click_count)
order	string	desc	Sort order (asc, desc)

Error Handling

The API uses conventional HTTP response codes to indicate success or failure.

Status Code	Description
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid API key
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Error Response Format

{
  "success": false,
  "error": {
    "code": "INVALID_URL",
    "message": "The provided URL is not valid"
  }
}

Code Examples

cURL

curl -X POST https://urlvanish.com/api/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/long-url",
    "alias": "my-link"
  }'

JavaScript

const response = await fetch('https://urlvanish.com/api/create', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://example.com/long-url',
    alias: 'my-link'
  })
});

const data = await response.json();
console.log(data);

Python

import requests

url = "https://urlvanish.com/api/create"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "url": "https://example.com/long-url",
    "alias": "my-link"
}

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

PHP

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://urlvanish.com/api/create');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'url' => 'https://example.com/long-url',
    'alias' => 'my-link'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

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

print_r($data);