API Documentation

Integrate LinkTrap into your applications with our powerful RESTful API

Table of Contents

Getting Started

Base URL

https://linktrap.co/api/v1

Requirements

  • Valid API key (obtainable from your dashboard)
  • HTTPS requests only
  • JSON request and response format
  • UTF-8 encoding

Rate Limits

1,000
requests/hour (Free)
10,000
requests/hour (Pro)
100,000
requests/hour (Enterprise)

Authentication

All API requests require authentication using an API key. Include your API key in the request header:

Request Header

Authorization: Bearer YOUR_API_KEY

⚠️ Security Note

Keep your API key secure and never expose it in client-side code. API keys have the same permissions as your user account.

Getting Your API Key

  1. Log in to your LinkTrap dashboard
  2. Navigate to Settings > API Keys
  3. Click "Generate New API Key"
  4. Copy and securely store your key

API Endpoints

Create Short Link

POST /api/v1/links

Request Body

{
  "url": "https://example.com/long-url",
  "custom_slug": "my-link",
  "title": "My Link Title",
  "description": "Optional description",
  "bot_url": "https://example.com/bot-page",
  "tags": ["marketing", "campaign"]
}

Response

{
  "success": true,
  "data": {
    "id": "abc123",
    "short_url": "https://linktrap.co/my-link",
    "original_url": "https://example.com/long-url",
    "created_at": "2024-01-01T12:00:00Z",
    "clicks": 0
  }
}

Get Link Information

GET /api/v1/links/{slug}

Response

{
  "success": true,
  "data": {
    "id": "abc123",
    "slug": "my-link",
    "original_url": "https://example.com/long-url",
    "title": "My Link Title",
    "clicks": 42,
    "created_at": "2024-01-01T12:00:00Z",
    "updated_at": "2024-01-02T15:30:00Z"
  }
}

Get Link Analytics

GET /api/v1/links/{slug}/analytics

Query Parameters

  • period - Time period (24h, 7d, 30d, 90d, all)
  • timezone - Timezone offset (optional)

List All Links

GET /api/v1/links

Query Parameters

  • page - Page number (default: 1)
  • limit - Items per page (default: 20, max: 100)
  • search - Search in titles and URLs
  • sort - Sort field (created_at, clicks, title)
  • order - Sort order (asc, desc)

Update Link

PUT /api/v1/links/{slug}

Delete Link

DELETE /api/v1/links/{slug}

Code Examples

JavaScript (Node.js)

const axios = require('axios');

const apiKey = 'YOUR_API_KEY';
const baseURL = 'https://linktrap.co/api/v1';

// Create a short link
async function createLink(url, customSlug = null) {
  try {
    const response = await axios.post(`\${baseURL}/links`, {
      url: url,
      custom_slug: customSlug
    }, {
      headers: {
        'Authorization': `Bearer \${apiKey}`,
        'Content-Type': 'application/json'
      }
    });
    
    return response.data;
  } catch (error) {
    console.error('Error creating link:', error.response.data);
  }
}

// Usage
createLink('https://example.com', 'my-link')
  .then(result => console.log(result));

Python

import requests
import json

API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://linktrap.co/api/v1'

def create_link(url, custom_slug=None):
    headers = {
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    }
    
    data = {'url': url}
    if custom_slug:
        data['custom_slug'] = custom_slug
    
    response = requests.post(
        f'{BASE_URL}/links',
        headers=headers,
        json=data
    )
    
    if response.status_code == 201:
        return response.json()
    else:
        print(f'Error: {response.status_code} - {response.text}')

# Usage
result = create_link('https://example.com', 'my-link')
print(result)

PHP

<?php

$apiKey = 'YOUR_API_KEY';
$baseUrl = 'https://linktrap.co/api/v1';

function createLink($url, $customSlug = null) {
    global $apiKey, $baseUrl;
    
    $data = ['url' => $url];
    if ($customSlug) {
        $data['custom_slug'] = $customSlug;
    }
    
    $ch = curl_init();
    curl_setopt_array($ch, [
        CURLOPT_URL => $baseUrl . '/links',
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $apiKey,
            'Content-Type: application/json'
        ],
        CURLOPT_POSTFIELDS => json_encode($data)
    ]);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    return json_decode($response, true);
}

// Usage
$result = createLink('https://example.com', 'my-link');
print_r($result);

?>

cURL

# Create a short link
curl -X POST \
  'https://linktrap.co/api/v1/links' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/long-url",
    "custom_slug": "my-link",
    "title": "My Link Title"
  }'

# Get link information
curl -X GET \
  'https://linktrap.co/api/v1/links/my-link' \
  -H 'Authorization: Bearer YOUR_API_KEY'

# Get analytics
curl -X GET \
  'https://linktrap.co/api/v1/links/my-link/analytics?period=7d' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Error Handling

The API uses conventional HTTP response codes to indicate the success or failure of requests. Codes in the 2xx range indicate success, 4xx indicate errors with the request, and 5xx indicate server errors.

HTTP Status Codes

200 OK - Request successful
201 Created - Resource successfully created
400 Bad Request - Invalid request parameters
401 Unauthorized - Invalid or missing API key
404 Not Found - Resource does not exist
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Server error

Error Response Format

{
  "success": false,
  "error": {
    "code": "INVALID_URL",
    "message": "The provided URL is not valid",
    "details": {
      "field": "url",
      "value": "invalid-url"
    }
  }
}

Common Error Codes

INVALID_URL - The provided URL is malformed
SLUG_TAKEN - Custom slug already exists
INVALID_SLUG - Custom slug format invalid
RATE_LIMITED - Too many requests
UNAUTHORIZED - Invalid API key
NOT_FOUND - Resource not found

Need Help?

Our API documentation is constantly evolving. If you need help or have suggestions, we're here for you.

Contact Support Visit Help Center