Introduction v4.0.0

Welcome to the LinkRun API documentation. Our API enables you to programmatically access and manage your shortened URLs, track analytics, and integrate LinkRun's functionality into your applications.

Base URL

https://linkrun.xyz/api/token/{token}

Authentication

All API requests require authentication using an API token. Tokens can be generated from your account dashboard.

Token Format

Include your API token in the URL path for all requests:

https://linkrun.xyz/api/token/your_api_token/endpoint

Rate Limits

The API implements rate limiting to ensure fair usage:

100 requests per hour per token
Rate limit counters reset every hour
Exceeding the limit returns a 429 status code

API Endpoints

GET /links

Retrieve all links associated with your account

{
    "links": [
        {
            "short_code": "abc123",
            "original_url": "https://example.com",
            "created_at": "2024-01-04T14:00:00Z",
            "visits": 42
        }
    ]
}

GET /links/total

Get the total number of links for the authenticated user

{
    "total_links": 42
}

GET /links/latest

Retrieve the 10 most recently created links

{
    "links": [
        {
            "short_code": "abc123",
            "original_url": "https://example.com",
            "created_at": "2024-01-04T14:00:00Z",
            "visits": 42
        },
        // ... more links
    ]
}

GET /links/{short_code}

Get detailed information about a specific link

{
    "short_code": "abc123",
    "original_url": "https://example.com",
    "created_at": "2024-01-04T14:00:00Z",
    "expires_at": "2024-02-04T14:00:00Z",
    "total_visits": 42,
    "statistics": {
        "browsers": [
            {
                "name": "Chrome",
                "count": 25,
                "percentage": 59.5
            }
        ],
        "platforms": [
            {
                "name": "Windows",
                "count": 20,
                "percentage": 47.6
            }
        ],
        "devices": [
            {
                "name": "Desktop",
                "count": 35,
                "percentage": 83.3
            }
        ]
    }
}

GET /account

Retrieve account information for the authenticated user

{
    "email": "user@example.com",
    "created_at": "2024-01-04T14:00:00Z",
    "total_links": 42
}

GET /links/clicks

Get the total number of clicks across all links

{
    "total_clicks": 156
}

GET /links/{short_code}/clicks

Get the number of clicks for a specific link

{
    "clicks": 42
}

POST /create-token

Generate a new API token (Note: Use command line tools like cURL, Python requests, or any other API client. This endpoint does not support direct browser access.)

{
    "message": "Token created successfully",
    "token": "your_api_token"
}
                    

# Python example using requests library
import requests
token = "your_api_token"
url = f"https://linkrun.xyz/api/token/{token}/create-token"
                        
response = requests.post(url)
data = response.json()
                    

# Using cURL
curl -X POST https://linkrun.xyz/api/token/your_api_token/create-token
                    

Error Responses

Common Error Codes

Status Code	Description
401	Invalid or missing API token
404	Requested resource not found
429	Rate limit exceeded (100 requests per hour)