API Documentation

Welcome to the zip1.io API documentation. Our API allows you to create and manage short links programmatically. Below you'll find detailed information on available endpoints, request parameters, and response formats.

1. Create Short Link

POST /api/create

This endpoint allows you to create a new short link.

Request Headers:

Headers
Content-Type: application/json

Request Body:

JSON
{
    "url": "https://example.com/very-long-url-that-needs-shortening",
    "alias": "custom-alias",  // Optional: custom short code
    "max-clicks": 100,  // Optional: limit number of clicks
    "password": "team2024@",  // Optional: password protection
    "description": "My important link"  // Optional: description
}

Parameters:

Parameter Type Required Description
url string Yes The long URL to be shortened
alias string No Custom alias for the short link (3-16 characters, alphanumeric and hyphens)
max-clicks integer No Maximum number of allowed clicks (minimum: 1)
password string No Password to protect the link
description string No Description for the link (max 100 characters)

Example Request:

cURL
curl -X POST http://zip1.io/api/create \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://github.com/username/awesome-project",
    "alias": "awesome",
    "max-clicks": 1000,
    "description": "My awesome GitHub project"
  }'

Success Response:

JSON • Status: 200 OK
{
    "message": "Shortened URL created successfully",
    "data": {
        "short_url": "http://zip1.io/awesome",
        "creation_time": "2024-01-15T10:30:45Z",
        "description": "My awesome GitHub project"
    }
}

Error Responses:

JSON • Status: 400 Bad Request
{
    "message": "Invalid URL format or missing required fields"
}
JSON • Status: 409 Conflict
{
    "message": "Alias already exists"
}

2. Get Link Statistics

GET /api/stats/{short_code}

Retrieve detailed statistics for a specific short link.

Path Parameters:

Parameter Type Description
short_code string The short code or alias of the link

Example Request:

cURL
curl -X GET http://zip1.io/api/stats/awesome

Success Response:

JSON • Status: 200 OK
{
    "message": "Statistics retrieved successfully",
    "data": {
        "short_code": "awesome",
        "total_clicks": 523,
        "unique_clicks": 421,
        "creation_date": "2024-01-15T10:30:45Z",
        "last_click": "2024-01-20T15:45:12Z",
        "click_limit": 1000,
        "is_password_protected": false,
        "top_countries": [
            {"country": "United States", "clicks": 234},
            {"country": "United Kingdom", "clicks": 89},
            {"country": "Germany", "clicks": 67}
        ],
        "recent_clicks": [
            {
                "timestamp": "2024-01-20T15:45:12Z",
                "country": "United States",
                "referrer": "twitter.com"
            }
        ]
    }
}

Error Response:

JSON • Status: 404 Not Found
{
    "message": "Short link not found"
}

3. Export Statistics

GET /api/export/{short_code}

Export detailed statistics for a short link in various formats.

Path Parameters:

Parameter Type Description
short_code string The short code or alias of the link

Query Parameters:

Parameter Type Required Description
format string No Export format: json, csv, or xlsx (default: json)

Example Requests:

cURL - JSON Format
curl -X GET http://zip1.io/api/export/awesome?format=json
cURL - CSV Format
curl -X GET http://zip1.io/api/export/awesome?format=csv \
  -o statistics.csv

Response:

The response will be in the requested format. For JSON, it returns detailed statistics. For CSV and XLSX formats, the response is a downloadable file.

Rate Limiting

Our API implements rate limiting to ensure fair usage:

  • Create Short Link: 10 requests per minute per IP
  • Get Statistics: 30 requests per minute per IP
  • Export Statistics: 5 requests per minute per IP

When rate limited, you'll receive a 429 status code with the following response:

JSON • Status: 429 Too Many Requests
{
    "message": "Rate limit exceeded. Please try again later.",
    "retry_after": 60
}

Best Practices

  • Always validate URLs on your end before sending them to our API
  • Handle rate limiting gracefully by implementing exponential backoff
  • Store the short URLs returned by our API for future reference
  • Use descriptive aliases when possible for better link management
  • Implement proper error handling for all possible response codes
  • Consider caching statistics data to reduce API calls

Code Examples

Python:

Python
import requests
import json

# Create a short link
def create_short_link(url, alias=None, max_clicks=None):
    endpoint = "http://zip1.io/api/create"
    payload = {"url": url}
    
    if alias:
        payload["alias"] = alias
    if max_clicks:
        payload["max-clicks"] = max_clicks
    
    response = requests.post(
        endpoint,
        headers={"Content-Type": "application/json"},
        data=json.dumps(payload)
    )
    
    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"Error: {response.json()['message']}")

# Get statistics
def get_stats(short_code):
    endpoint = f"http://zip1.io/api/stats/{short_code}"
    response = requests.get(endpoint)
    
    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"Error: {response.json()['message']}")

# Example usage
try:
    # Create a short link
    result = create_short_link(
        url="https://github.com/username/project",
        alias="myproject",
        max_clicks=1000
    )
    print(f"Short URL: {result['data']['short_url']}")
    
    # Get statistics
    stats = get_stats("myproject")
    print(f"Total clicks: {stats['data']['total_clicks']}")
    
except Exception as e:
    print(f"Error: {e}")

JavaScript (Node.js):

JavaScript
const axios = require('axios');

// Create a short link
async function createShortLink(url, options = {}) {
    try {
        const response = await axios.post('http://zip1.io/api/create', {
            url: url,
            ...options
        }, {
            headers: {
                'Content-Type': 'application/json'
            }
        });
        
        return response.data;
    } catch (error) {
        throw new Error(error.response.data.message);
    }
}

// Get statistics
async function getStats(shortCode) {
    try {
        const response = await axios.get(`http://zip1.io/api/stats/${shortCode}`);
        return response.data;
    } catch (error) {
        throw new Error(error.response.data.message);
    }
}

// Example usage
(async () => {
    try {
        // Create a short link
        const result = await createShortLink('https://github.com/username/project', {
            alias: 'myproject',
            'max-clicks': 1000,
            description: 'My awesome project'
        });
        console.log(`Short URL: ${result.data.short_url}`);
        
        // Get statistics
        const stats = await getStats('myproject');
        console.log(`Total clicks: ${stats.data.total_clicks}`);
        
    } catch (error) {
        console.error(`Error: ${error.message}`);
    }
})();

🤖 AI Integration (Model Context Protocol)

Zip1.io supports the Model Context Protocol (MCP), enabling AI assistants like Claude to interact with the URL shortener directly.

MCP Endpoint:

GET /mcp

Get server information and available tools.

Setup for Claude Code (Recommended):

Claude Code has native HTTP MCP support. Simply run this command:

Terminal
claude mcp add --transport http zip1 http://zip1.io/mcp

Setup for Claude Desktop:

⚠️ Important: Claude Desktop currently only supports stdio-based MCP servers, not HTTP servers. We recommend using Claude Code for zip1.io's MCP integration.

Available MCP Tools:

  • create_short_url - Create shortened URLs with custom aliases, passwords, and max clicks
  • get_url_stats - Retrieve detailed analytics for shortened URLs
  • validate_url - Check if URLs can be shortened
  • generate_short_code - Generate random short code suggestions

Example Usage:

After configuring Claude Code, you can use natural language prompts like:

  • "Shorten https://github.com/my-repo with alias 'repo'"
  • "Get statistics for short code 'docs'"
  • "Create a password-protected link for https://example.com/secret"
📚 Full MCP Documentation: For detailed information about the MCP integration, see our MCP documentation.

Need Help?

If you have any questions or need assistance with our API: