REST API Documentation

1. Generate API Key

Sign in and visit API Keys Settings to create your first API key.

2. Authentication

All API requests require authentication using an API key in the Authorization header:

3. Base URL

JavaScript

// Using fetch API
const apiKey = 'uc_live_YOUR_API_KEY';

async function createLink(targetUrl, customSlug) {
  const response = await fetch('https://useclick.io/api/v1/links', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      target_url: targetUrl,
      slug: customSlug
    })
  });

  const data = await response.json();
  return data;
}

// Usage
createLink('https://example.com', 'my-link')
  .then(link => console.log('Created:', link))
  .catch(err => console.error('Error:', err));

Python

import requests

API_KEY = 'uc_live_YOUR_API_KEY'
BASE_URL = 'https://useclick.io/api/v1'

headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
}

# Create a new link
def create_link(target_url, custom_slug=None):
    payload = {'target_url': target_url}
    if custom_slug:
        payload['slug'] = custom_slug

    response = requests.post(
        f'{BASE_URL}/links',
        headers=headers,
        json=payload
    )
    return response.json()

# List all links
def list_links():
    response = requests.get(
        f'{BASE_URL}/links',
        headers=headers
    )
    return response.json()

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

PHP

<?php
$apiKey = 'uc_live_YOUR_API_KEY';
$baseUrl = 'https://useclick.io/api/v1';

function createLink($targetUrl, $customSlug = null) {
    global $apiKey, $baseUrl;

    $data = ['target_url' => $targetUrl];
    if ($customSlug) {
        $data['slug'] = $customSlug;
    }

    $ch = curl_init("$baseUrl/links");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Authorization: Bearer $apiKey",
        'Content-Type: application/json'
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}

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

Ruby

require 'net/http'
require 'json'

API_KEY = 'uc_live_YOUR_API_KEY'
BASE_URL = 'https://useclick.io/api/v1'

def create_link(target_url, custom_slug = nil)
  uri = URI("#{BASE_URL}/links")

  payload = { target_url: target_url }
  payload[:slug] = custom_slug if custom_slug

  request = Net::HTTP::Post.new(uri)
  request['Authorization'] = "Bearer #{API_KEY}"
  request['Content-Type'] = 'application/json'
  request.body = payload.to_json

  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
    http.request(request)
  end

  JSON.parse(response.body)
end

# Usage
link = create_link('https://example.com', 'my-link')
puts "Created: #{link}"

Pagination Parameters

When listing links or clicks, use these query parameters to paginate results:

GET /api/v1/links?page=2&limit=25

Filtering Links

Filter your links list with these query parameters:

GET /api/v1/links?campaign=summer-sale&sort=clicks_desc

Response Metadata

Paginated responses include metadata to help you navigate results:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 237,
    "pages": 5,
    "has_next": true,
    "has_prev": false
  }
}

1. Secure Your API Keys

• Never expose API keys in client-side code (JavaScript running in browsers)
• Store keys in environment variables, not in your codebase
• Use separate keys for development and production environments
• Rotate keys periodically and immediately if compromised
• Revoke unused keys from the API Keys Settings page

2. Handle Rate Limits Gracefully

• Implement exponential backoff when receiving 429 errors
• Check the Retry-After header for recommended wait time
• Cache responses when possible to reduce API calls
• Consider upgrading your plan if you consistently hit rate limits

// Example: Exponential backoff
async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || Math.pow(2, i);
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      continue;
    }

    return response;
  }
  throw new Error('Max retries exceeded');
}

3. Validate Input Data

• Ensure target URLs are valid and include the protocol (https:// or http://)
• Slugs must be lowercase, alphanumeric, and use hyphens only (no spaces or special characters)
• Check that campaign and folder names exist before referencing them
• Validate country codes against ISO 3166-1 alpha-2 standard (US, GB, DE, etc.)

4. Use Pagination for Large Datasets

• Don't fetch all links at once—use pagination to retrieve data in chunks
• Start with limit=50 and adjust based on your needs
• Check has_next in the response to know if more pages exist
• Implement cursor-based pagination for real-time data if available

5. Handle Errors Properly

• Always check response status codes and handle errors appropriately
• Parse error messages from the response body for user-friendly feedback
• Log API errors for debugging and monitoring
• Implement fallback behavior for non-critical API failures

// Example: Error handling
try {
  const response = await fetch(url, options);
  const data = await response.json();

  if (!response.ok) {
    throw new Error(`API Error: ${data.error.message}`);
  }

  return data;
} catch (error) {
  console.error('Failed to create link:', error);
  // Handle error appropriately
}

6. Monitor API Usage

• Track your API request volume to stay within rate limits
• Monitor error rates to detect integration issues early
• Set up alerts for unusual API activity or failures
• Review API logs regularly for optimization opportunities

401 Unauthorized Error

Symptom: All requests return "Unauthorized" error.

Causes:

• Missing or invalid API key
• API key not included in the Authorization header
• Incorrect header format (should be Bearer uc_live_...)
• API key has been revoked or expired

Solution: Verify your API key is correct, check the Authorization header format, and ensure the key hasn't been revoked in your API Keys Settings.

429 Rate Limit Exceeded

Symptom: Requests fail with "Too Many Requests" error.

Causes:

• Exceeded your plan's request limit (100-3,000 req/min depending on plan)
• Too many requests in a short time window
• Multiple API clients using the same key

Solution: Implement exponential backoff, check the Retry-After header, reduce request frequency, or upgrade your plan for higher limits.

400 Validation Error - Duplicate Slug

Symptom: Creating a link fails with "Slug already exists" error.

Causes:

• The custom slug you specified is already used by another link in your account
• Slugs must be unique across your entire account

Solution: Choose a different slug or omit the slug field to auto-generate a unique random slug.

404 Not Found Error

Symptom: Request returns "Resource not found" error.

Causes:

• The link slug you're requesting doesn't exist
• The link belongs to a different user or organization
• The link was deleted
• Typo in the slug or endpoint URL

Solution: Verify the slug is correct, check that you own the link, and ensure the link hasn't been deleted.

403 Forbidden - Feature Not Available

Symptom: Request fails with "Feature not available on your plan" error.

Causes:

• Trying to use a feature that requires a higher plan (e.g., geo-targeting on Free plan)
• Link quota exceeded for your plan
• Campaign or folder limits reached

Solution: Upgrade your plan to access the feature, or remove unused links/campaigns to free up quota.

CORS Errors (Browser Requests)

Symptom: API requests from browser JavaScript fail with CORS errors.

Causes:

• API keys should never be used in client-side JavaScript
• The UseClick API does not support CORS for security reasons

Solution: Make API requests from your backend server, not directly from the browser. Use a server-side proxy or serverless function to call the API.

500 Internal Server Error

Symptom: Request fails with "Internal Server Error."

Causes:

• Temporary server issue
• Unexpected error in the API

Solution: Retry the request after a short delay. If the problem persists, contact support at [email protected] with the request details.

Is the API available on all plans?

Yes! All plans from Free to Business have API access. Rate limits vary by plan: Free (100 req/min), Starter (300 req/min), Growth (600 req/min), Pro (1,200 req/min), Business (3,000 req/min).

Can I create multiple API keys?

Yes, you can create multiple API keys for different applications or environments (development, staging, production). This allows you to revoke keys independently if one is compromised.

Do API-created links count towards my plan limit?

Yes. All links created via the API count towards your plan's total link limit (Free: 10, Starter: 300, Growth: 1,000, Pro: 5,000, Business: 25,000). You'll receive a 403 error if you attempt to exceed your limit.

Can I use the API to update link analytics?

No. Click analytics are automatically collected when users click your links. The API provides read-only access to analytics data via GET /api/v1/clicks.

Is there a webhook system for real-time events?

Not yet. Webhooks for click events, link creation, and other real-time notifications are planned for a future release. Currently, you need to poll the API to check for new clicks.

How do I test the API without affecting my production data?

Create a separate API key for testing and use it with test links. You can also use a different campaign or folder to organize test links separately from production links. There's no sandbox environment currently.

Can I bulk create links via the API?

Yes, but you need to make multiple POST /api/v1/links requests (one per link). Be mindful of rate limits—use a delay between requests or implement batch processing with retries. For large bulk uploads (100+ links), consider using the CSV bulk upload feature in the dashboard instead.

What happens if I delete a link via the API?

Deleting a link via DELETE /api/v1/links/:slug permanently removes the link and all its associated click analytics data. This action cannot be undone, so use with caution.

Are there official API client libraries or SDKs?

Not officially at this time. However, the API follows REST conventions and works with any HTTP client library (fetch, axios, requests, curl, etc.). Community-contributed SDKs may be available—check our GitHub or documentation updates.

Can I use the API to manage team members or billing?

No. The current API focuses on link management and analytics. Team member management, billing, and account settings are only available through the web dashboard.

What's the API version policy?

The current API is version 1 (/api/v1). We'll maintain backward compatibility and provide advance notice before deprecating endpoints. New features may be added without version changes if they don't break existing integrations.

How do I report API bugs or request features?

Email us at [email protected] with details about the bug or feature request. Include your API request/response examples, error messages, and expected behavior.

Combining Multiple Features

You can use multiple advanced features together on the same link:

{
  "target_url": "https://example.com/vip-content",
  "slug": "vip-access",
  "password": "VIP2025",
  "expires_at": "2025-12-31T23:59:59Z",
  "click_limit": 100,
  "mature_warning": false
}