How to Use a URL Shortener API: Developer Guide 2026

Integrating a URL shortener into an application is a well-defined problem with a well-defined solution space — but the decisions that determine whether an integration holds up in production are not obvious from the basic documentation. Which API to use for personal versus organizational use cases, how authentication works, what the rate and volume limits mean for capacity planning, what operations are available beyond link creation, and how the Regular API and Team API differ architecturally — these are the decisions this guide covers. The goal is to give developers a clear map of what Cuttly's API surface includes, so integration choices are made deliberately rather than discovered at the wrong moment.

For the complete parameter reference, response schemas, and endpoint specifications, the official documentation at cutt.ly/api-documentation/regular-api and cutt.ly/api-documentation/team-api is the authoritative reference. This guide focuses on decisions and capabilities.

---

Regular API vs Team API: The Architectural Decision

Cuttly provides two distinct APIs: the Regular API and the Team API. They serve different integration contexts, and the decision between them is architectural rather than a matter of preference.

The Regular API authenticates with a personal API key generated in an individual user's account settings. Links created through the Regular API belong to that individual's account, appear in their personal dashboard, and count against their plan's monthly limits. The key is entirely tied to that person — if the account is cancelled or the key is regenerated, every integration using the old key stops working immediately. The Regular API is the right choice for solo developers, personal projects, and individual automation workflows where one person owns both the Cuttly account and the integration.

The Team API authenticates with a key generated in Team Settings for a specific Cuttly Team workspace. That key is not attached to any individual user. It persists as long as the team exists, survives personnel changes without disruption, and can be regenerated by any Team Owner or Admin. Links created through the Team API belong to the team's workspace and appear in the team dashboard. The Team API is available from the Team plan ($99/month) and is the correct foundation for any organizational integration — a CRM, a CMS, an e-commerce platform, a notification system — where the integration belongs to the company and not a specific person.

The practical rule: if the integration runs on behalf of an organization and needs to survive individual people leaving, use the Team API. If it is a personal automation that one developer owns entirely, the Regular API is sufficient. The base endpoint URLs and some parameter names differ between the two APIs — the full specifications for each are in their respective documentation pages.

Authentication

How API Keys Work

Both APIs use API key authentication. The key is passed as a query parameter — named key — in every request. It is not sent in a request header. All calls must be made over HTTPS, which prevents the key from being exposed in transit.

Because the key appears as a URL query parameter, it will appear in any system that logs full request URLs: server logs, proxy logs, network monitoring tools. This makes key management discipline important. API keys should be stored as environment variables or in a dedicated secrets manager, never hardcoded in source code, and calls to the API must always be made server-side. A key in client-side JavaScript or embedded in a mobile app's static assets is exposed to anyone who inspects the source — the API key protects the account, and leaking it means anyone can create and manage links on behalf of that account.

Generating a Regular API Key

Log in to Cuttly and go to Edit Account. The API section shows the current key and provides the option to regenerate it. Regenerating invalidates the previous key immediately — any integrations using the old key must be updated before or immediately after regeneration to avoid downtime.

Generating a Team API Key

Log in to Cuttly, navigate to the desired Team from the left sidebar, open Team Settings, and go to the API section. Only Team Owners and Admins can generate the Team API key. The same regeneration behavior applies: generating a new key immediately invalidates the previous one. Because multiple people can manage the Team API key (any Owner or Admin), key rotation is operationally cleaner than the Regular API — it does not require access to a specific person's account settings.

Rate Limits

Per-Plan API Call Limits

Cuttly enforces rate limits on a per-account basis, measured within a rolling 60-second window. All API calls — link creation, editing, stats retrieval — draw from the same limit pool. An account running multiple integrations simultaneously shares a single rate limit budget.

Handling 429 Responses

When the rate limit is exceeded, the API returns HTTP 429 Too Many Requests. Production integrations must handle this explicitly — 429 should trigger a retry with exponential backoff, not a hard failure. The approach is to wait progressively longer between retries: one second, then two, then four, with random jitter added to prevent synchronized retry bursts when multiple processes hit the limit at the same moment.

For batch operations that need to create many links in sequence, pacing requests deliberately below the plan limit is more reliable than firing at full speed and relying on retry logic. On the Single plan (60 calls per 60 seconds), one request per second stays safely within limits. On Team (180 calls per 60 seconds), roughly three requests per second is sustainable. Planning for the rate limit in the integration architecture prevents cascading retry storms during high-volume runs.

Monthly Volume Limits

Separate from the per-minute rate limit, each plan has a monthly cap on the total number of links that can be created. These limits reset on the first day of each month and are tracked per account (Regular API) or per team (Team API).

When the monthly limit is reached, the API returns a status indicating the cap has been hit. Production integrations that create links at a predictable daily rate should monitor volume as it approaches the plan limit and upgrade before the limit is reached mid-month — an unexpected halt to automated link creation during a live campaign is a meaningful operational failure. An integration creating 200 links per day on the Single plan exhausts its 5,000-link monthly allowance around day 25.

Link Creation: What Parameters Are Available

Link creation is the primary operation of both APIs. Both require two inputs: the API key and the destination URL. Several optional parameters give the calling application control over how the link is created.

Destination URL and URL Encoding

The destination URL is required and must be properly URL-encoded before being passed to the API. The documentation specifies using urlencode() (in PHP) or the equivalent encoding function in the language being used. A destination URL that includes UTM parameters, additional query strings, or any special characters must be encoded — failing to encode means those characters are misinterpreted as part of the API request's own query string, resulting in a malformed request or an incorrect destination.

When using URL-building utilities that construct query strings automatically (such as URLSearchParams in JavaScript or similar libraries in other languages), encoding is handled automatically for the values passed into those utilities. When constructing API request URLs manually as string concatenation, explicit encoding of the destination URL value is required.

Custom Alias

The optional name parameter sets a custom alias — the back-half of the short link that appears after the domain. If no alias is specified, a random short alias is generated automatically. Custom aliases must be unique within the domain's namespace: on the cutt.ly domain, across all users of the platform; on a branded custom domain, within that domain's own alias database. If the requested alias is already taken, the Regular API returns status 3. Integrations must decide how to handle this: fall back to a modified alias, surface the conflict for manual resolution, or treat it as idempotent success if the link was already created by a previous run with the same alias.

Branded Domain

The Regular API and Team API handle branded domain selection differently, and this is one of the most important distinctions to understand before building an integration.

In the Regular API, the userDomain parameter is set to the value 1 — not a domain name string. This instructs the API to use whichever custom domain is currently marked as active in the account's dashboard. The domain itself is selected in Edit Account → Custom Domains, not in the API call. Only one domain can be the active domain at a time in this model. This means an integration using userDomain=1 creates links on whatever domain the account owner has set as active — changing the active domain in the dashboard changes the behavior of every subsequent API call that uses userDomain=1.

In the Team API, the domain parameter accepts the domain name directly as a string (for example, go.yourbrand.com). Each API call can specify a different domain, as long as that domain is assigned to the team. This makes multi-domain integrations possible within a single team context — the calling application can route different links to different branded domains based on its own logic, without needing to change any dashboard settings between calls.

In both cases, the domain must be verified and properly configured in Cuttly before it can be used via API. Using a domain that is not verified, not owned by the account, or not assigned to the team returns an error. Verifying the domain configuration in the dashboard before deploying an API integration prevents this class of production failure.

noTitle

When a short link is created, Cuttly by default fetches the page title from the destination URL's meta tags and stores it as the link's title. This adds a small latency to the API response because it requires an outbound request to the destination page. The noTitle parameter (set to 1) disables this behavior, producing a faster API response at the cost of not auto-populating the title. This parameter is available on the Team Enterprise plan and is primarily useful in high-throughput bulk creation workflows where response time matters more than having titles populated automatically.

Public Statistics

The public parameter (set to 1) makes the click statistics for the created link publicly accessible — anyone with the short link can view its analytics without needing a Cuttly account. This is available from the Single plan. If not set, statistics are private by default and visible only to the account owner. Public statistics can also be set or changed later via the edit endpoint.

UTM Parameters

UTM parameters are not separate API parameters. They are part of the destination URL. The correct approach is to build the full destination URL — including all UTM parameters — before passing it to the API. The API receives that complete URL, URL-encoded as required, shortens it, and stores it as the destination. When someone clicks the short link, they are redirected to the full UTM-tagged URL, and the UTM values pass through to Google Analytics or whichever analytics platform the destination page uses.

This means UTM construction is entirely the responsibility of the calling application. The API does not add, modify, or validate UTM parameters — it shortens whatever destination it receives. If a UTM parameter contains spaces or special characters, those must be percent-encoded as part of encoding the full destination URL. An improperly encoded UTM value results in a misformed destination URL that breaks attribution.

Tags

Tags in Cuttly serve two purposes: organizing links in the dashboard, and powering Campaigns — the aggregated analytics view that groups all links sharing a tag and shows their combined performance. Tags are not set during link creation. They are set through the edit endpoint after the link has been created, using the full short link URL as the identifier and the tag value as the parameter.

This two-step flow — create, then tag — is worth knowing before designing an integration. If every link needs a tag, the integration must issue two API calls per link: one to create and one to tag. Both calls count against the rate limit. For integrations at high volume, this doubles the API call budget required per link and should be factored into throughput planning against plan rate limits.

Link Analytics via API

Both the Regular API and Team API include a stats endpoint. The stats endpoint takes the full shortened URL — not just the alias — as its input and returns a set of click analytics for that link. Understanding the response structure before building an analytics integration avoids surprises.

What Data the Stats Endpoint Returns

For a link that exists and is owned by the account (status 1 in the response), the stats endpoint returns:

• clicks — total click count for the link
• title — the stored title of the link
• fullLink — the original destination URL
• shortLink — the shortened URL
• facebook — clicks originating from Facebook
• twitter — clicks originating from Twitter
• linkedin — clicks originating from LinkedIn
• rest — clicks from other sources
• bots — detected bot clicks
• refs — an array of referrer domains with click counts per domain
• devices → geo — an array of countries with click counts per country (identified by country code)
• devices → dev — an array of device types with click counts per type

The response also includes a status field: status 1 means the link was found and data was returned; status 0 means the link does not exist; status 2 means the API key is invalid. Always check this status before attempting to use the analytics data — do not assume a successful HTTP response means the link exists.

Date-Range Filtering

The Regular API supports date_from and date_to parameters for filtering analytics to a date range, available from the Team plan. The Team API supports the same parameters without a plan restriction at the team level. Dates are formatted as YYYY-MM-DD. Date-range filtering enables incremental data pulls — fetching only the period since the last sync — which is important for analytics pipelines that query a large number of links on a regular schedule.

Link Editing via API

From the Single plan, both APIs support editing existing short links. The edit endpoint identifies the link by its full short URL and applies the specified operation. Understanding exactly what can be edited, and what the constraints are per plan, prevents integration designs that rely on capabilities not available at the chosen plan level.

Changing the Destination URL

The destination URL of an existing short link can be updated — the short link continues to work but now redirects to the new destination. The new destination must be URL-encoded. One important constraint: on the Starter and Single plans, the new destination must share the same root domain as the original destination. Changing a short link's destination to a completely different domain — for example, updating a link that pointed to a product page on one website to point to a page on a different website — requires the Team plan. If the integration needs to redirect links across different domains, plan selection must account for this.

Changing the Alias

The alias of an existing link can be updated to a new value, as long as the new alias is not already taken. Changing the alias changes the short link URL itself — the old short link URL no longer works after the alias is changed. Any systems that stored the old short link URL need to be updated.

Adding or Changing a Tag

Tags on existing links can be added or changed via the edit endpoint. This is the only way to apply tags to links — the creation endpoint does not include a tag parameter in the Regular API.

Mobile Redirects and Deep Linking

The edit endpoint supports configuring alternative redirect destinations for specific mobile operating systems. When mobile redirect is configured for a short link, users on Android, iOS, or Windows Mobile are redirected to a different URL than desktop users. This is used to route mobile users directly to an app or a mobile-optimized page while desktop users continue to the standard destination.

For Android, the edit endpoint also supports deferred deep linking: providing an Android package ID alongside the deep link destination. When a user clicks the short link and does not have the app installed, they are redirected to the Google Play Store page for the app. After installation, the Install Referrer API passes attribution data from the link to the app. An optional referrer parameter carries a custom payload — a URL-encoded string — through the install flow, enabling attribution and segmentation at the install level.

Link Expiration

Short links can be configured to expire either after a specific date or after a specified number of clicks. Once the expiration condition is met, further clicks on the short link are redirected to a designated expiration URL rather than the original destination. Setting expiration to 0 removes it. Expiration is useful for time-limited promotions, single-use links, or access-controlled content where the link should stop working after a certain point.

A/B and A/B/C Testing

The edit endpoint can configure a short link to split traffic between two or three destination URLs at specified percentage splits — an A/B or A/B/C test. Each variation receives a configured share of clicks: for A/B, the B variation receives the specified percentage and the original destination receives the remainder; for A/B/C, both B and C variations receive specified percentages with the constraint that their combined share cannot exceed 100%. This enables controlled experiments where different landing pages, offers, or content variations are tested under the same short link.

Unique Click Counting

Unique click counting filters repeat clicks from the same visitor within a time window so they count as a single click rather than multiple. On the Single plan, unique counting uses a fixed 15-minute window. On Team plans, the window is configurable between 15 and 1440 minutes (24 hours), allowing the integration to define what counts as a "unique" visit for its specific measurement needs. Unique counting can be disabled by setting the parameter to 0.

Password Protection

Short links can be password-protected — visitors are prompted to enter a password before being redirected to the destination. Password protection is set via the edit endpoint and uses a POST request rather than a GET request, which is the only POST operation in the Cuttly API. The password value is sent in the request body as form data, not as a query parameter. Removing the password is done by sending an empty password value. The full request format is documented in the API reference.

Edit Response Status Codes

The edit endpoint returns a status of 1 for success, 2 if the database write failed, 3 if the link does not exist or is not owned by the account, and 4 (for destination URL and mobile destination changes only) if the provided URL did not pass validation.

TRAI SMS Compliance

For integrations serving the Indian SMS market under TRAI regulations, both APIs support configuration with TRAI-compliant custom domains and the generic 2s.ms domain with a registered HEADER. This produces short links in the format required by TRAI DLT: domain/HEADER/alias. The Regular API handles this through the userDomain parameter with a TRAI-configured active domain. The Team API uses the domain parameter combined with a header parameter. The setup process — including HEADER registration, domain configuration, and team dashboard setup — is covered in the Cuttly TRAI compliance documentation.

Response Status Codes for Link Creation (Regular API)

The Regular API creation endpoint returns the outcome of the request in a status field inside the response JSON. Every production integration should handle each of these explicitly:

• Status 7 — success. The link was created. The response includes the short link URL, full destination URL, creation date, and link title.
• Status 1 — the submitted URL belongs to a link-shortening domain (the link has already been shortened).
• Status 2 — the submitted value is not a valid URL.
• Status 3 — the requested alias is already taken.
• Status 4 — the API key is invalid.
• Status 5 — the link failed validation (contains invalid characters).
• Status 6 — the link's domain is blocked.
• Status 8 — the monthly link creation limit has been reached.

An HTTP 200 response does not mean the link was created. Status 7 is the only successful creation outcome. HTTP-level errors also occur: 401 Unauthorized with auth: false in the JSON when the API key is incorrect, and descriptive error messages for rate limit hits and expired subscriptions.

Common Integration Patterns

Idempotent Link Creation

Many integrations are triggered by events — a new CRM deal, a published article, a new product listing — and those events can sometimes be delivered more than once due to retry logic, network failures, or at-least-once delivery guarantees in message queues and webhooks. An integration that creates a new short link with a random alias on each trigger produces duplicate links for duplicate events — fragmented analytics and polluted link inventories.

The solution is deterministic aliases: derive the alias from the stable identifier of the entity being linked (deal ID, article slug, product SKU). If the same event triggers the integration twice, the second attempt requests the same alias. The API returns status 3 (alias taken), which the integration treats as confirmation that the link already exists — no action needed. This makes link creation idempotent: triggering it multiple times with the same input produces the same result without side effects. This pattern is important for any integration running in an environment where event delivery is not guaranteed to be exactly once.

Asynchronous Link Creation

URL shortening is a side-effect operation — it enriches an entity with a short link but is not itself a core transaction. This has an important implication for where to place the API call in an application's architecture. If link creation happens synchronously as part of the main request path — a product is created, and the API call to create its short link blocks the response — then the latency and availability of the Cuttly API directly affects the user experience of the primary operation.

For most integrations, asynchronous link creation is the better design: the primary operation completes immediately with a null or pending short link value, and a background job creates the short link and updates the record when complete. If the API is temporarily unavailable, the job queue retries automatically without the user experiencing any failure. The short link appears within seconds or minutes, which is generally acceptable. Synchronous link creation is only appropriate when the short link URL is genuinely required in the immediate response to the user.

Batch Link Creation with Rate Pacing

Importing or migrating a large inventory — a product catalogue, an article archive, a historical campaign link set — requires creating many links in sequence. The rate limit defines the maximum sustainable throughput: on the Single plan, 60 links per minute; on Team, 180 per minute; on Enterprise, 360 per minute. A batch job should pace its requests deliberately to stay within this budget rather than relying on retry logic to absorb the overflow. Pacing also makes progress predictable: at 60 requests per minute, a batch of 5,000 links takes approximately 83 minutes to process.

Scheduled Analytics Sync

An analytics integration queries the stats endpoint on a schedule — daily, weekly — for a set of active campaign links and writes the data to an internal database or warehouse. With date-range filtering (Team plan), each run fetches only the increment since the last sync, keeping each run's request count proportional to the number of days elapsed rather than the full lifetime of the links. This data can be joined with other marketing metrics for campaign-level performance reporting without relying on the Cuttly dashboard as the reporting interface.

Which Plan to Use

The Free plan ($0) includes API access at 3 calls per 60 seconds and 30 links per month on the cutt.ly domain. The only practical use for the Free plan in an API context is validating that the integration works before committing to a paid plan.

The Starter plan ($12/month) provides 6 calls per 60 seconds, 300 links per month, and 30 branded domain links per month via API. It is suitable for low-volume integrations that need branded domain links — a small CMS creating a few links per day, or a personal project with occasional branded link creation.

The Single plan ($25/month) provides 60 calls per 60 seconds, 5,000 links per month, and 1,000 branded domain links per month via API. It unlocks the edit endpoint — destination changes, mobile redirects, expiration, A/B testing, unique click counting, and deletion. This is the appropriate plan for most individual developer integrations with moderate volume and full editing capabilities.

The Team plan ($99/month) provides the Team API with 180 calls per 60 seconds and 20,000 links per month. It adds date-range filtering for analytics, the direct domain parameter for multi-domain integrations, and the organizational key management that production deployments require. This is the appropriate plan for any integration that belongs to a company rather than an individual.

The Enterprise plan ($149/month) provides 360 calls per 60 seconds, 50,000 links per month, and the noTitle parameter for faster responses in high-throughput bulk creation workflows.

Create a free Cuttly account to generate your API key and start building. Registration required; free plan available with no credit card needed.