How to Use a URL Shortener API: Developer Guide 2026

Integrating a URL shortener API into an application or workflow is one of the more straightforward API integration tasks a developer will encounter — but doing it correctly, for production use rather than quick prototyping, requires understanding a set of decisions that do not appear in the basic "shorten a URL" quickstart: which authentication model to use for organizational versus personal integrations, how to handle rate limits without degrading application performance, when to use the Regular API versus the Team API, how to create branded domain links programmatically, how to retrieve and process analytics data, and what the monthly volume limits mean for capacity planning. This guide covers all of it with practical code examples and the specific Cuttly API parameters that matter for common integration patterns.

---

Regular API vs Team API: Which to Use

This is the most important architectural decision for any production API integration with Cuttly, and it is worth getting right before writing a line of code.

The Regular API authenticates with a personal API key tied to an individual Cuttly user account. The key is generated in the individual's account settings. Links created through the Regular API are associated with that individual's account, appear in their dashboard, and are subject to that account's plan limits. If the individual who owns the API key leaves the organization and their account is cancelled, every integration using that key breaks immediately.

The Team API authenticates with an API key tied to a Cuttly Team workspace rather than to any individual. The key is generated in the Team Settings of a specific team. Links created through the Team API are associated with the team's dashboard. The key persists as long as the team exists — it does not depend on any individual user's continued membership. Any Team Owner or Admin can regenerate the key (invalidating the previous one, so integrations must be updated when this happens). The Team API is available from the Team plan ($99/month).

Decision rule: for personal or solo developer use, the Regular API is appropriate. For any organizational integration — a CRM that creates links for each new client, a CMS that auto-shortens published URLs, an e-commerce platform that generates short links for product pages — use the Team API. Personal keys create organizational dependencies on individuals; team keys do not.

Authentication

Both the Regular API and Team API use API key authentication passed as a query parameter in the request URL.

Generating Your API Key

Regular API key: Log in to Cuttly → Edit Account → API section → copy or regenerate your API key.

Team API key: Log in to Cuttly → navigate to the desired Team (left sidebar) → Team Settings → API section → Generate API key. Only Team Owners and Admins can generate the Team API key. Generating a new key invalidates the previous one — update any integrations using the old key immediately after regeneration.

Using the API Key

The API key is passed as a query parameter in every request. For the Regular API: ?key=YOUR_API_KEY. For the Team API: ?key=YOUR_TEAM_API_KEY. The key is not passed in a header — it is always a query parameter. For production environments, store the API key as an environment variable and never hardcode it in source code.

The base URLs differ between the Regular and Team APIs. Consult the official Cuttly API documentation at cutt.ly/cuttly-api for current base URL structures and endpoint paths.

Rate Limits: Per-Plan Limits and Handling 429 Responses

Rate Limit by Plan

Handling 429 Rate Limit Responses

When the rate limit is exceeded, Cuttly returns an HTTP 429 Too Many Requests response. Applications must handle this gracefully rather than failing or silently dropping requests. The standard approach: exponential backoff with jitter.

// NOTE: Run this server-side only (Node.js / backend).
// Store apiKey as an environment variable.
async function shortenWithRetry(url, apiKey, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(
        `https://cutt.ly/api/api.php?key=${apiKey}&short=${encodeURIComponent(url)}`
      );
 
      if (response.status === 429) {
        // Exponential backoff: 1s, 2s, 4s with jitter
        const delay = Math.pow(2, attempt) * 1000 + Math.random() * 500;
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
 
      const data = await response.json();
      return data;
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
    }
  }
}

For batch operations (creating many links in sequence), implement a request queue with rate limiting rather than firing all requests simultaneously. At 60 calls/60s on the Single plan, you can safely send 1 request per second; at 180 calls/60s on Team, 3 requests per second.

// Simple rate-limited queue for batch link creation
async function createLinksWithRateLimit(urls, apiKey, callsPerMinute = 60) {
  const delayMs = (60 / callsPerMinute) * 1000; // ms between calls
  const results = [];
 
  for (const url of urls) {
    const result = await shortenUrl(url, apiKey);
    results.push(result);
    await new Promise(resolve => setTimeout(resolve, delayMs));
  }
 
  return results;
}

Creating a Short Link via API

Minimal Request — cutt.ly Domain

The simplest link creation request requires only the API key and the destination URL. A random alias is auto-generated.

// NOTE: Run this server-side only (Node.js / backend).
// Never include your API key in browser-executed JavaScript —
// it would be exposed in the page source and network inspector.

// Minimal: shorten a URL on the cutt.ly domain
const response = await fetch(
  `https://cutt.ly/api/api.php?key=${API_KEY}&short=${encodeURIComponent(destinationUrl)}`
);
const data = await response.json();
// data.url.shortLink contains the created short link URL
// data.url.status: 7 = success, other values indicate errors

Status Codes in the Response

The API response includes a status field in the url object. Common values:

• 7 — OK. The short link was created successfully.
• 1 — The link comes from a domain that already shortens links (it has already been shortened).
• 2 — The entered value is not a valid URL.
• 3 — The preferred alias (name) is already taken.
• 4 — Invalid API key.
• 5 — The link did not pass validation (includes invalid characters).
• 6 — The link is from a blocked domain.
• 8 — Monthly link limit reached. Upgrade your plan to add more links.

Always check the status field before using shortLink — do not assume success from an HTTP 200 response alone.

// NOTE: Run this server-side only (Node.js / backend).
// Store apiKey as an environment variable — never hardcode it in source code.
async function createShortLink(destinationUrl, apiKey) {
  const response = await fetch(
    `https://cutt.ly/api/api.php?key=${apiKey}&short=${encodeURIComponent(destinationUrl)}`
  );
  const data = await response.json();
 
  if (data?.url?.status !== 7) {
    throw new Error(`Link creation failed: status ${data?.url?.status}`);
  }
 
  return data.url.shortLink; // e.g. "https://cutt.ly/aBcDeF"
}

Creating Branded Domain Links via API

Branded domain links require the userDomain parameter. The domain must already be verified and connected in the Cuttly dashboard before it can be used via API.

How userDomain works: The parameter accepts the value 1 (not a domain name string). When set to 1, Cuttly uses the custom domain that is currently set as active in your account dashboard. You must set your verified branded domain as active in Edit Account → Custom Domains before making API calls. Only one domain can be active at a time for the Regular API.

// NOTE: Run this server-side only (Node.js / backend).
// Never place your API key in browser-executed JavaScript.

// Create a link on the active branded domain
// Prerequisite: set your domain as active in Edit Account → Custom Domains
const params = new URLSearchParams({
  key: API_KEY,      // store in environment variable, never hardcode
  short: destinationUrl,
  userDomain: '1'   // value is always "1" — uses the active domain from your account
});
 
const response = await fetch(
  `https://cutt.ly/api/api.php?${params.toString()}`
);
const data = await response.json();
// data.url.shortLink will be: https://go.yourbrand.com/ALIAS

If userDomain is provided but the domain is not verified in the account, the API returns a status error. Validate domain availability in the dashboard before relying on it in production API calls.

Monthly branded domain link limits via API: 30/month on Starter, 1,000/month on Single. For higher branded domain API volumes, the Team plan (20,000/month) is required.

Setting a Custom Alias

The name parameter sets a custom alias (back-half) for the short link.

// NOTE: Run this server-side only (Node.js / backend).
// Prerequisite: set go.yourbrand.com as active in Edit Account → Custom Domains.
const params = new URLSearchParams({
  key: API_KEY,      // store in environment variable, never hardcode
  short: destinationUrl,
  userDomain: '1',   // value is always "1" — uses the active domain from your account
  name: 'product-sku-00123' // custom alias
});
 
const response = await fetch(
  `https://cutt.ly/api/api.php?${params.toString()}`
);
// Result: https://go.yourbrand.com/product-sku-00123

Aliases must be unique within the domain's namespace. If the requested alias already exists, the API returns status 3 (alias taken). Handle this in production code — either generate a fallback alias or surface the conflict for manual resolution.

// NOTE: Run this server-side only (Node.js / backend).
// The domain parameter is used only to reconstruct the expected URL on retry;
// userDomain is always passed as "1" to the Regular API (uses the active domain).
async function createWithAlias(destinationUrl, alias, domain, apiKey) {
  const params = new URLSearchParams({
    key: apiKey,
    short: destinationUrl,
    userDomain: '1',  // always "1" for Regular API — uses the active domain in account
    name: alias
  });
 
  const response = await fetch(`https://cutt.ly/api/api.php?${params}`);
  const data = await response.json();
 
  if (data?.url?.status === 3) {
    // Alias taken — try with a suffixed alias
    return createWithAlias(destinationUrl, `${alias}-2`, domain, apiKey);
  }
 
  if (data?.url?.status !== 7) {
    throw new Error(`Failed: status ${data?.url?.status}`);
  }
 
  return data.url.shortLink;
}

Adding Tags and UTM Parameters

Tags help organize links in the dashboard and enable Cuttly Campaigns (Team plan) for aggregated analytics.

Important — tag is an edit parameter, not a shortening parameter: In the Regular API, tag is only available via the edit endpoint, not during link creation. To add a tag, first create the link, then make a second API call using the edit parameter with tag.

// NOTE: Run this server-side only (Node.js / backend).

// Step 1: Create the short link
const params = new URLSearchParams({
  key: API_KEY,
  short: destinationUrl,
  userDomain: '1',   // uses the active domain in your account
  name: 'product-sku-123'
});
 
// Step 2: Add a tag via the edit endpoint (separate call)
const editParams = new URLSearchParams({
  key: API_KEY,
  edit: 'https://cutt.ly/product-sku-123',  // the short link created above
  tag: 'q3-launch-campaign'
});

UTM parameters should be appended to the destination URL before passing it to the API — not as separate API parameters. Build the full destination URL including UTM parameters, then pass that complete URL as the short parameter.

function buildDestinationWithUtm(baseUrl, utmParams) {
  const url = new URL(baseUrl);
  Object.entries(utmParams).forEach(([key, value]) => {
    url.searchParams.set(key, value);
  });
  return url.toString();
}
 
const destination = buildDestinationWithUtm(
  'https://yourdomain.com/product-page',
  {
    utm_source: 'email',
    utm_medium: 'newsletter',
    utm_campaign: 'q3-launch'
  }
);
 
// destination = https://yourdomain.com/product-page?utm_source=email&utm_medium=newsletter&utm_campaign=q3-launch
// Now create the short link with this destination
const params = new URLSearchParams({ key: API_KEY, short: destination });

Retrieving Analytics for a Short Link

The Cuttly API provides a stats endpoint to retrieve click analytics for any short link associated with the account. The stats endpoint returns total clicks, unique clicks, device breakdown, OS breakdown, browser breakdown, country breakdown, and referrer breakdown.

// Retrieve analytics for a short link
// shortCode is the alias part of the short link (e.g. "product-sku-123")
async function getStats(shortCode, apiKey) {
  const params = new URLSearchParams({
    key: apiKey,
    stats: shortCode
  });
 
  const response = await fetch(
    `https://cutt.ly/api/api.php?${params.toString()}`
  );
  const data = await response.json();
 
  // data.stats contains click data
  return data.stats;
}
 
// Example response structure (abbreviated):
// {
//   clicks: 847
// }

Date-Range Filtering (Team Plan+)

From the Team plan, the date_from and date_to parameters filter analytics to a specific date range. Dates are formatted as YYYY-MM-DD.

// Get stats for a specific date range (Team plan+)
const params = new URLSearchParams({
  key: TEAM_API_KEY,
  stats: shortCode,
  date_from: '2026-06-01',
  date_to: '2026-06-30'
});

Editing a Short Link After Creation

From the Single plan, the Cuttly API supports editing existing short links. Available edit operations: change the destination URL (source URL), add or change a tag, delete the link, and configure unique click counting.

// Change the destination URL of an existing short link
async function updateDestination(shortCode, newDestination, apiKey) {
  const params = new URLSearchParams({
    key: apiKey,
    edit: shortCode,
    source: newDestination
  });
 
  const response = await fetch(
    `https://cutt.ly/api/api.php?${params.toString()}`
  );
  const data = await response.json();
  return data;
}
 
// Update tag for an existing link
async function updateTag(shortCode, newTag, apiKey) {
  const params = new URLSearchParams({
    key: apiKey,
    edit: shortCode,
    tag: newTag
  });
 
  const response = await fetch(
    `https://cutt.ly/api/api.php?${params.toString()}`
  );
  return await response.json();
}

An important constraint from Cuttly's documentation: the Starter plan and Single plan can only change the destination URL to a URL from the same domain. The Team and Enterprise plans allow changing the destination to any URL. Factor this into production application design — if your integration needs to update a short link to a completely different domain (e.g., redirecting from one client's site to another), this requires the Team plan.

Common Integration Patterns

CRM: Auto-Generate a Short Link for Each New Contact

A CRM integration creates a unique tracked short link for each new contact or deal — used in personalized email communications, for tracking which outreach generates engagement from each specific contact.

// Called from CRM webhook on new contact creation
async function onNewContact(contact, apiKey) {
  const destination = `https://yourdomain.com/proposal?client=${contact.id}`;
 
  const link = await createShortLink(destination, {
    apiKey,
    domain: 'go.yourbrand.com',
    alias: `client-${contact.id}`,
    tag: `crm-contact-${new Date().getFullYear()}`
  });
 
  // Store the short link URL back to the CRM contact record
  await crm.updateContact(contact.id, { trackingLink: link });
 
  return link;
}

CMS: Auto-Shorten Published Article URLs

A CMS integration creates a short link for each newly published article — used in social media sharing and email newsletter distributions where the canonical article URL is long.

// Called from CMS on article publish event
async function onArticlePublished(article, apiKey) {
  const alias = article.slug.substring(0, 20); // truncate long slugs
 
  try {
    const shortLink = await createWithAlias(
      article.canonicalUrl,
      alias,
      'go.yourdomain.com',
      apiKey
    );
 
    await cms.updateArticleMeta(article.id, { shortUrl: shortLink });
    return shortLink;
  } catch (error) {
    console.error(`Short link creation failed for ${article.slug}:`, error);
    // Fallback: use canonical URL without shortening
    return article.canonicalUrl;
  }
}

E-Commerce: Short Link per Product for Multi-Channel Sharing

An e-commerce integration creates a short link for each product at the time of listing, tagged by product category for analytics aggregation.

// Batch product link creation with rate limiting
async function createProductLinks(products, apiKey) {
  const DELAY_MS = 1000; // 60 calls/min on Single plan = 1/sec
  const results = [];
 
  for (const product of products) {
    try {
      const link = await createWithAlias(
        product.pageUrl,
        `prd-${product.sku}`,
        'go.yourbrand.com',
        apiKey
      );
      results.push({ sku: product.sku, link, status: 'created' });
    } catch (error) {
      results.push({ sku: product.sku, link: null, status: 'failed', error: error.message });
    }
 
    await new Promise(r => setTimeout(r, DELAY_MS));
  }
 
  return results;
}

Analytics Dashboard: Aggregating Link Performance

Pulling analytics for a set of links to build an internal performance dashboard — weekly stats per campaign tag.

// Retrieve stats for a list of short codes and aggregate
async function getCampaignStats(shortCodes, apiKey, dateFrom, dateTo) {
  const allStats = await Promise.allSettled(
    shortCodes.map(code =>
      getStats(code, apiKey, dateFrom, dateTo)
        .then(stats => ({ code, stats, status: 'ok' }))
        .catch(err => ({ code, stats: null, status: 'error', error: err.message }))
    )
  );
 
  const successfulStats = allStats
    .filter(r => r.status === 'fulfilled' && r.value.status === 'ok')
    .map(r => r.value);
 
  return {
    totalClicks: successfulStats.reduce((sum, s) => sum + (s.stats?.allTime || 0), 0),
    byLink: successfulStats.map(s => ({ code: s.code, clicks: s.stats?.allTime }))
  };
}

Team API Setup and Key Management

For organizations moving from personal API tokens to the Team API, the setup process:

1. Create or access your Cuttly Team. From the Team plan dashboard, navigate to the Teams section in the left sidebar. Select the team you want to use for the integration, or create a new one specifically for the integration use case.

2. Generate the Team API key. In Team Settings → API section, click Generate API key. The key is shown once — copy it immediately. Store it as a secure environment variable, not in code.

3. Add the branded domain to the team. If the integration will create branded domain links, the domain must be added to the team. Only the Team Owner can add a custom domain to a team. The domain must already be verified in the owner's main dashboard. Go to Team Settings → add domain.

4. Test with a low-volume request before production deployment. Create a single test link via the Team API, verify the response, and confirm the link appears in the team dashboard before deploying to production.

5. Key rotation procedure. When the Team API key needs to be rotated (security practice or after a team member departure): generate a new key in Team Settings. The old key is immediately invalidated. Update all integrations with the new key. If multiple integrations share the same Team API key, coordinate the rotation to minimize downtime.

Where to Find the Full API Reference

This guide covers the core integration patterns and production considerations. The complete API reference — including all available parameters, full response schemas, error code definitions, and endpoint specifications for both the Regular API and Team API — is in the official Cuttly API documentation.

Regular API documentation: cutt.ly/api-documentation/regular-api

Team API documentation: cutt.ly/api-documentation/team-api

The API is available on all plans including free. Free plan: 3 calls/60s, 30 cutt.ly links/month, no branded domain links. For branded domain API access, start from the Starter plan. For production organizational integrations, the Team plan with Team API is the appropriate foundation.