Cuttly API Shorten, Manage and Analyze Links Programmatically

Cuttly provides a REST API that lets you create short links, manage them, retrieve analytics and integrate URL shortening directly into your applications, scripts and automated workflows. The API is available on all plans including free — no paid subscription required to start. For teams and shared workspaces, the Team API provides the same capabilities operating on a shared link library with role-based access.

This page covers both APIs: the Regular API for individual accounts and the Team API for team workspaces. Both use standard GET requests and return JSON responses.

Regular API vs Team API — Which to Use

Cuttly provides two separate API endpoints depending on the account context you want to operate in.

Use the Regular API when you are building integrations for your personal Cuttly account — individual scripts, personal automation flows, solo developer projects. Use the Team API when links need to be created in a shared team workspace — agency workflows, multi-user applications, shared branded domain pipelines.

Getting Your API Key

Regular API key: Log in to your Cuttly account and go to Edit Account. Your API key is displayed there. Copy it — this is the key parameter in all Regular API requests.

Team API key: Log in to your Cuttly account, go to your Team workspace and open the Team edit page. The Team API key is displayed there. This key is separate from your personal API key and requires a minimum Team subscription plan.

Keep your API key secure — it authenticates all requests made on your behalf. Do not expose it in client-side code or public repositories.

Regular API — Complete Reference

Shorten a URL — Minimum Request

The simplest Regular API request requires only two parameters: your API key and the URL-encoded destination URL.

$url = urlencode('https://yoursite.com/page');
$json = file_get_contents("https://cutt.ly/api/api.php?key=YOUR_KEY&short=$url");
$data = json_decode($json, true);
// $data['url']['shortLink'] — your new short link

Important: Always pass the destination URL through urlencode() (PHP), urllib.parse.quote() (Python) or the equivalent in your language. Without URL encoding, any parameters, UTM tags or special characters in the destination URL will break the API request.

Shorten with Custom Alias (Slug)

Add the optional name parameter to specify a custom alias for the short link. If the alias is already taken, the API returns status 3.

Custom alias availability: Free plan allows 3 custom slugs per month. Starter: 30/month. Single and above: unlimited.

Shorten with Branded Domain

Add userDomain=1 to use your active branded domain instead of cutt.ly. Requires a paid subscription and an active branded domain connected in your account.

Additional Shortening Parameters

Response Status Codes

Every Regular API shortening response includes a url.status field. A successful shortening returns status 7.

When status is 7, the response also includes:

Edit a Short Link

The Regular API supports comprehensive link editing via the edit parameter. Most editing operations require Single plan or above.

Edit Response Status Codes

Retrieve Link Statistics

The Regular API returns click analytics for any short link you own via the stats parameter.

Team API — Complete Reference

The Team API operates on a shared team workspace. It requires a minimum Team subscription plan and uses a separate API key available in the Team edit page. The endpoint and parameter structure differ from the Regular API.

Team API endpoint: https://cutt.ly/team/API/index.php

Team API: Shorten a URL

$url = urlencode('https://yoursite.com/page');
$json = file_get_contents(
  "https://cutt.ly/team/API/index.php?key=TEAM_KEY&action=shorten&url=$url&name=campaign&domain=yourbrnd.link"
);
$data = json_decode($json, true);

Key difference from Regular API: the Team API uses url (not short) for the destination URL, action=shorten is a required parameter, and the domain is specified by name (domain=yourbrnd.link) rather than by a flag (userDomain=1).

Team API: Edit a Short Link

The Team API supports the same link editing operations as the Regular API. Use action=edit and the short link URL.

Supported edit parameters in the Team API are identical to the Regular API: tag, name, source, title, delete, password, expire, expireCond, expireRedirect, mobile, destination, unique, abtest and the AB test variation parameters.

Team API: Retrieve Link Statistics

TRAI SMS Compliance via API

Cuttly supports TRAI-compliant SMS link shortening via both APIs. TRAI (Telecom Regulatory Authority of India) regulations require that SMS messages from businesses include a registered Header (sender ID) in the shortened URL format. Cuttly supports this via the 2s.ms domain and via custom branded domains with Headers.

Regular API — TRAI with Branded Domain

Team API — TRAI with 2s.ms Domain

Team API — TRAI with Custom Domain and Header

API Rate Limits Per Plan

Exceeding the rate limit returns a Too many requests error. Implement exponential backoff in your application when handling this error. Monthly link limits are separate from rate limits — reaching the monthly limit returns status 8 in the shortening response.

API Error Reference

Regular API Errors

Team API Errors

Practical API Use Cases

Understanding the API endpoints is the starting point. Understanding how to combine them into real workflows is where the value is. Here are the most common patterns developers use with the Cuttly API.

Use Case 1: Automated Link Creation on Content Publish

The most common Cuttly API integration pattern: every time a new piece of content is published — a blog post, a product page, a news article — a script automatically creates a branded Cuttly short link for it. The script runs as a post-publish webhook, calls the Regular API with the new page URL, and stores the returned short link in a database or CMS field alongside the content record.

import urllib.parse
import requests

key = 'YOUR_API_KEY'
url = urllib.parse.quote('https://yoursite.com/new-article')
name = 'new-article'

r = requests.get(
    f'https://cutt.ly/api/api.php?key={key}&short={url}&name={name}&userDomain=1'
)
data = r.json()

if data['url']['status'] == 7:
    short_link = data['url']['shortLink']
    print(f'Short link created: {short_link}')
else:
    print(f'Error: status {data["url"]["status"]}')

Use Case 2: Bulk Link Creation for Campaign Launch

Before a campaign launch, a script creates multiple short links — one per channel, one per product variant or one per audience segment — each with a descriptive slug and a campaign tag. The script loops through a list of destinations and slugs, respects the API rate limit with a delay between requests, and outputs a CSV of short links ready to distribute to the campaign team.

$key = 'YOUR_API_KEY';
$links = [
    ['url' => 'https://yoursite.com/offer', 'name' => 'offer-email'],
    ['url' => 'https://yoursite.com/offer', 'name' => 'offer-sms'],
    ['url' => 'https://yoursite.com/offer', 'name' => 'offer-instagram'],
];

foreach ($links as $link) {
    $url = urlencode($link['url']);
    $name = $link['name'];
    $json = file_get_contents(
        "https://cutt.ly/api/api.php?key={$key}&short={$url}&name={$name}&userDomain=1"
    );
    $data = json_decode($json, true);
    if ($data['url']['status'] === 7) {
        echo $data['url']['shortLink'] . PHP_EOL;
    }
    sleep(1); // respect rate limit
}

Use Case 3: Dynamic Destination Update

A campaign link is distributed across email, print and social media. Midway through the campaign, the destination page URL changes — a new landing page replaces the original, or a seasonal offer page is swapped in. Instead of redistributing new links (impossible for printed materials) or breaking the link, a single API call updates the destination URL. Every existing share of the short link immediately redirects to the new destination.

$key = 'YOUR_API_KEY';
$short_link = 'yourbrnd.link/summer-sale';
$new_destination = urlencode('https://yoursite.com/summer-sale-2026');

$json = file_get_contents(
    "https://cutt.ly/api/api.php?key={$key}&edit={$short_link}&source={$new_destination}"
);
$data = json_decode($json, true);
// $data['status'] === 1 means success

Use Case 4: Analytics Retrieval for Reporting

A weekly reporting script pulls click analytics for all campaign links and compiles them into a spreadsheet or dashboard. For each short link in the campaign, the script calls the Regular API with the stats parameter, retrieves click data, and writes it to a database or exports to CSV.

import requests

key = 'YOUR_API_KEY'
short_link = 'yourbrnd.link/summer-sale'

r = requests.get(
    f'https://cutt.ly/api/api.php?key={key}&stats={short_link}'
)
data = r.json()
print(data)
# Returns: total clicks, unique clicks, devices, countries, referrers, dates

Use Case 5: Team API for Agency Multi-Client Workflow

An agency manages ten client accounts, each with its own branded domain, in a single Cuttly Team workspace. A Python script processes a CSV of content URLs for each client, creates short links under the correct client domain using the Team API, and outputs a report per client. All links are created in the shared workspace — accessible to all authorized team members via the Cuttly dashboard.

import urllib.parse
import requests

team_key = 'YOUR_TEAM_API_KEY'

clients = [
    {'url': 'https://client-a.com/product', 'name': 'product-launch', 'domain': 'clienta.link'},
    {'url': 'https://client-b.com/offer',   'name': 'spring-offer',   'domain': 'clientb.link'},
]

for client in clients:
    url = urllib.parse.quote(client['url'])
    r = requests.get(
        f"https://cutt.ly/team/API/index.php"
        f"?key={team_key}&action=shorten&url={url}"
        f"&name={client['name']}&domain={client['domain']}"
    )
    data = r.json()
    print(data)

Use Case 6: A/B Test Setup via API

A marketing team wants to split traffic between two landing page variants. Using the edit API with the abtest parameter, they configure a 50/50 A/B test on an existing short link — 50% of clicks go to variant A (the original destination), 50% go to variant B. After a week, they pull stats via API, compare click data per variant and update the source URL to the winning variant.

$key = 'YOUR_API_KEY';
$short_link = 'yourbrnd.link/landing';
$variant_b = urlencode('https://yoursite.com/landing-variant-b');

$json = file_get_contents(
    "https://cutt.ly/api/api.php?key={$key}"
    . "&edit={$short_link}"
    . "&abtest=1"           // 1 = A/B test
    . "&abtest_b=50"        // 50% to variant B
    . "&abtest_bvariation={$variant_b}"
);
$data = json_decode($json, true);
// status 1 = success

Use Case 7: Link Expiration for Time-Limited Offers

A flash sale promotion has a hard end date. The short link is created normally, then the expiration is set via API — after the sale end date, the link automatically stops redirecting to the sale page and redirects instead to the main shop homepage. No manual link management required at the end of the promotion.

$key = 'YOUR_API_KEY';
$short_link = 'yourbrnd.link/flash-sale';
$redirect_after = urlencode('https://yoursite.com/shop');

$json = file_get_contents(
    "https://cutt.ly/api/api.php?key={$key}"
    . "&edit={$short_link}"
    . "&expire=1"                      // 1 = date-based expiration
    . "&expireCond=2026-06-30"         // expires on 30 June 2026
    . "&expireRedirect={$redirect_after}"
);
$data = json_decode($json, true);

JavaScript / Node.js API Integration

For Node.js applications and serverless functions, the Cuttly API is accessible via standard fetch or axios. Always handle the URL encoding server-side — never expose your API key in client-side JavaScript.

const key = process.env.CUTTLY_API_KEY;
const destination = encodeURIComponent('https://yoursite.com/page');
const name = 'my-link';

const response = await fetch(
  `https://cutt.ly/api/api.php?key=${key}&short=${destination}&name=${name}&userDomain=1`
);
const data = await response.json();

if (data.url.status === 7) {
  console.log('Short link:', data.url.shortLink);
} else {
  console.error('API error, status:', data.url.status);
}

Handling API Responses Correctly

The Cuttly API always returns JSON. A robust integration handles all possible status codes rather than assuming success. Common mistakes and how to avoid them:

• Always check url.status before using url.shortLink. Status 7 is the only success state. All other values indicate an error that must be handled — do not assume the response contains a short link.
• Always URL-encode the destination. Raw URLs with query parameters, UTM tags or special characters will cause status 5 (validation failed). Use urlencode(), urllib.parse.quote() or encodeURIComponent() depending on your language.
• Handle status 3 (alias taken). If you generate slugs programmatically, build a retry mechanism that appends a suffix when the first slug is taken.
• Implement rate limit backoff. At high request volumes — Single plan (60 req/60s) or above — implement exponential backoff when receiving Too many requests errors.
• Store returned short links. The API does not provide a "list all links" endpoint — store the url.shortLink value returned at creation time in your own database for later editing or stats retrieval.
• Team API: always include action. Missing the action parameter in a Team API request returns 400 Incorrect action — the most common Team API mistake.

No-Code Alternatives to the API

If you need to automate Cuttly link creation without writing code, Cuttly integrates with major no-code and low-code automation platforms. See the full integrations page for setup guides.

Plan Guide for API Usage

The Free plan ($0) includes API access for link shortening and statistics retrieval. Rate limit: 3 requests/60s. Monthly limit: 30 links. No branded domain via API on free plan (userDomain=1 requires paid plan).

The Starter plan ($12/month) adds userDomain=1 support for branded domains via API. Rate limit: 6 requests/60s. Monthly limit: 300 links. Destination URL editing via source parameter available (same domain only).

The Single plan ($25/month) unlocks the full editing API — password, expiration, mobile redirects, A/B testing, unique click windows, public stats. Rate limit: 60 requests/60s. Monthly limit: 5,000 links. Unlimited custom slugs.

The Team plan ($99/month) enables the Team API. Rate limit: 180 requests/60s. Monthly limit: 20,000 links. Unique click window configurable from 15 to 1440 minutes.

The Team Enterprise plan ($149/month) adds noTitle=1 parameter for maximum API response speed. Rate limit: 360 requests/60s. Monthly limit: 50,000 links.

Full API documentation at cutt.ly/cuttly-api  ·  See all plans and pricing