API Documentation - Cabiux | Developer Guide

Introduction

What is Cabiux?

Cabiux is an intelligent URL shortening platform that automatically detects mobile apps and creates deep links. When users click your links on mobile devices, they're taken directly into the relevant app (if installed) for a seamless experience.

Key Features

Intelligent Deep Linking - Automatically routes users to native apps when available
Real-time Analytics - Track clicks, devices, locations, and conversion rates
Custom Short Codes - Create branded, memorable links
UTM Parameters - Built-in campaign tracking support
QR Code Generation - Generate QR codes for any link
Link Expiration - Set expiry dates or click limits
Branded Domains - Use your own domain for short links

Supported Apps

Cabiux automatically creates deep links for 50+ popular apps including:

Social: Instagram, TikTok, Twitter/X, Facebook, LinkedIn, Snapchat, Pinterest

E-commerce: Amazon, eBay, Etsy, Shopify stores, AliExpress

Media: YouTube, Spotify, Apple Music, Netflix, Twitch, SoundCloud

Productivity: Slack, Notion, Trello, Asana, Google Drive, Dropbox

Authentication

All API requests (except login) require authentication using JSON Web Tokens (JWT). You'll receive a token when you log in, which must be included in the Authorization header of subsequent requests.

Step 1: Obtain a Token

Send a POST request to the login endpoint with your credentials:

Request

POST /api/auth/login
Content-Type: application/json

{
  "email": "your@email.com",
  "password": "your-password"
}

                        Response
                    

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": 1704067200,
  "user": {
    "id": 1,
    "email": "your@email.com",
    "name": "Your Name",
    "plan": "medium"
  }
}
                    

Step 2: Use the Token

Include the token in the Authorization header with the Bearer prefix:

                        Header Format
                    
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Tip:

Tokens expire after 24 hours. Store the expires_at timestamp and refresh your token before it expires.

Base URL

All API endpoints are relative to the base URL of your Cabiux instance:

https://your-domain.com/api

For example, to create a link, you would send a request to:

POST https://your-domain.com/api/links

Create Link

POST /api/links

Creates a new short link with optional deep linking, UTM parameters, and expiration settings. The system automatically detects if the destination URL belongs to a supported app and generates appropriate deep links.

Request Body Parameters

Parameter	Type	Required	Description
original_url	string	Required	The destination URL to shorten. Must be a valid URL starting with http:// or https://
custom_short_code	string	Optional	Custom short code (3-50 chars, alphanumeric and hyphens). If not provided, a random 6-character code is generated.
title	string	Optional	A friendly name for the link (for your reference in the dashboard)
enable_deep_linking	boolean	Optional	Enable automatic deep linking to mobile apps. Default: `true`
utm_source	string	Optional	UTM source parameter (e.g., "newsletter", "twitter")
utm_medium	string	Optional	UTM medium parameter (e.g., "email", "social")
utm_campaign	string	Optional	UTM campaign parameter (e.g., "spring_sale_2024")
expires_at	string (ISO 8601)	Optional	Expiration date/time. After this time, the link will return a 410 Gone status.
max_clicks	integer	Optional	Maximum number of clicks allowed. After reaching this limit, the link expires.
campaign_id	integer	Optional	ID of a campaign to associate this link with

Example Request

cURL

curl -X POST https://your-domain.com/api/links \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "original_url": "https://www.instagram.com/cabiux",
    "custom_short_code": "follow-us",
    "title": "Instagram Follow Link",
    "enable_deep_linking": true,
    "utm_source": "email",
    "utm_medium": "newsletter",
    "utm_campaign": "weekly_digest"
  }'

Example Response

                                Response (201 Created)
                            

{
  "short_url": "https://your-domain.com/follow-us",
  "link": {
    "id": 42,
    "short_code": "follow-us",
    "original_url": "https://www.instagram.com/cabiux",
    "title": "Instagram Follow Link",
    "click_count": 0,
    "enable_deep_linking": true,
    "app_name": "Instagram",
    "utm_source": "email",
    "utm_medium": "newsletter",
    "utm_campaign": "weekly_digest",
    "created_at": "2024-01-15T10:30:00Z"
  }
}
                            

List Links

GET /api/links

Retrieves a paginated list of all your links, sorted by creation date (newest first).

Query Parameters

Parameter	Type	Default	Description
limit	integer	50	Number of links to return (max: 100)
offset	integer	0	Number of links to skip (for pagination)

Example Response

                                Response (200 OK)
                            

{
  "links": [
    {
      "id": 42,
      "short_code": "follow-us",
      "original_url": "https://www.instagram.com/cabiux",
      "click_count": 156,
      "enable_deep_linking": true,
      "created_at": "2024-01-15T10:30:00Z"
    }
    // ... more links
  ],
  "total": 127,
  "limit": 50,
  "offset": 0
}
                            

Get Link

GET /api/links/{id}

Retrieves detailed information about a specific link by its ID.

Update Link

PUT /api/links/{id}

Updates an existing link. You can modify the title, destination URL, deep linking settings, UTM parameters, and expiration settings. The short code cannot be changed after creation.

Delete Link

DELETE /api/links/{id}

Permanently deletes a link. This action cannot be undone. All analytics data for this link will also be deleted.

Warning:

Deleted links cannot be recovered. The short code will become available for reuse after deletion.

Get Analytics

GET /api/analytics/{shortCode}

Retrieves comprehensive analytics for a specific link including click counts, device breakdowns, geographic data, and time-series data.

Query Parameters

Parameter	Type	Default	Description
days	integer	30	Number of days to include in the analytics (max: 365)

Example Response

                                Response (200 OK)
                            

{
  "total_clicks": 1234,
  "unique_clicks": 892,
  "deep_link_rate": 78.5,
  "clicks_by_device": {
    "mobile": 834,
    "desktop": 356,
    "tablet": 44
  },
  "clicks_by_os": {
    "iOS": 512,
    "Android": 322,
    "Windows": 289,
    "macOS": 67,
    "Linux": 44
  },
  "clicks_by_country": {
    "US": 623,
    "UK": 198,
    "DE": 156,
    "CA": 89
  },
  "clicks_by_date": [
    {"date": "2024-01-15", "clicks": 45},
    {"date": "2024-01-14", "clicks": 62}
  ],
  "recent_clicks": [...]
}
                            

Deep Link Rate:

The deep_link_rate shows the percentage of clicks that successfully opened in a native app rather than a web browser.

QR Codes

GET /api/links/{id}/qrcode

Generates a QR code for the specified link. The QR code points to the short URL and will trigger deep linking when scanned on mobile devices.

Query Parameters

Parameter	Type	Default	Description
size	integer	256	QR code size in pixels (min: 64, max: 1024)
format	string	png	Response format: `png` (binary image) or `datauri` (base64 data URI)

Example Usage

# Download as PNG image
curl -o qrcode.png "https://your-domain.com/api/links/42/qrcode?size=512" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get as data URI (for embedding in HTML)
curl "https://your-domain.com/api/links/42/qrcode?format=datauri" \
  -H "Authorization: Bearer YOUR_TOKEN"
                            

Campaigns

Campaigns help you organize and track groups of related links. Create campaigns for marketing initiatives, product launches, or any collection of links you want to analyze together.

POST /api/campaigns

Create a new campaign to organize your links.

                                Request Body
                            

{
  "name": "Spring Sale 2024",
  "description": "Links for our spring promotional campaign"
}
                            

GET /api/campaigns

List all your campaigns with their link counts and total clicks.

GET /api/campaigns/{id}/links

Get all links belonging to a specific campaign.

Deep Linking

Deep linking is the core feature of Cabiux. When enabled, the system automatically detects supported apps in your destination URLs and generates the appropriate deep links.

How It Works

You create a short link to a supported app URL (e.g., Instagram profile)
User clicks the short link on their mobile device
Cabiux detects the user's device and operating system
If the app is likely installed, Cabiux attempts to open it directly
If the app isn't installed, users are redirected to the web version

App Detection:

Cabiux uses URL pattern matching to identify supported apps. For example, any URL containing instagram.com will automatically generate Instagram deep links.

Branded Domains

Use your own domain for short links instead of the default Cabiux domain. This improves brand recognition and click-through rates.

POST /api/domains

Add a custom domain to your account. You'll need to verify ownership via DNS.

POST /api/domains/{id}/verify

Verify domain ownership after adding the required DNS records.

Data Export

Export your links and analytics data in CSV format for external analysis or backup purposes.

GET /api/export/links

Export all your links as a CSV file.

GET /api/export/analytics/{shortCode}

Export click-level analytics data for a specific link as CSV.

Rate Limits

API rate limits vary by plan. Exceeding limits will result in a 429 Too Many Requests response.

Small Plan

60

requests/minute

Medium Plan

120

requests/minute

Large Plan

300

requests/minute

Tip:

If you're hitting rate limits, consider batching your requests or implementing exponential backoff in your integration.

Error Handling

The API uses standard HTTP status codes and returns error details in JSON format.

                        Error Response Format
                    
{
  "error": "Description of what went wrong"
}

HTTP Status Codes

Code	Status	Description
200	OK	Request succeeded
201	Created	Resource successfully created
400	Bad Request	Invalid request parameters or body
401	Unauthorized	Missing or invalid authentication token
403	Forbidden	Valid token but insufficient permissions
404	Not Found	Requested resource doesn't exist
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Something went wrong on our end

SDKs & Libraries

While we don't currently offer official SDKs, our REST API is straightforward to use with any HTTP client. Here are examples in popular languages:

JavaScript (Node.js)

JavaScript

const createLink = async (url, token) => {
  const response = await fetch('https://your-domain.com/api/links', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ original_url: url })
  });
  return response.json();
};

Python

import requests

def create_link(url, token):
    response = requests.post(
        'https://your-domain.com/api/links',
        headers={'Authorization': f'Bearer {token}'},
        json={'original_url': url}
    )
    return response.json()

PHP

$ch = curl_init('https://your-domain.com/api/links');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'original_url' => $url
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch));
curl_close($ch);