Developers · 9 min read · Updated June 10, 2026

URL Shortener API Guide: Create Short Links Programmatically

Creating short links one at a time in a dashboard works until it doesn't. The moment you need a link per ad variant, per email recipient, per release, or per generated QR code, clicking through a web form becomes the bottleneck — and the typos start. A URL shortener API turns link creation into a single HTTP request you can call from a script, a backend, a CI job, or a no-code automation.

This guide covers the practical side: how authentication with API keys and scopes works, how to make your first request, the automation patterns that come up most often, and how to handle rate limits and errors so your integration keeps working at 2 a.m. Examples use the ReSlug API, but the concepts transfer to any link platform.

What a URL shortener API actually does

At its core, a link API exposes the same operations as the dashboard — create, read, update, and delete short links — as REST endpoints that accept and return JSON. Create a link by POSTing a destination URL; the response contains the generated short URL and an ID you can use later to update the destination, attach tags, or pull click analytics.

Beyond CRUD, the platforms worth building on also expose analytics (clicks per link with geo, device, and referrer breakdowns), custom domains, QR codes, and bio pages through the same API, so anything you can do by hand you can automate. ReSlug's interactive reference lives at api.reslug.com/docs if you want to follow along with real endpoints.

Authentication: API keys and scopes

Link APIs almost universally authenticate with an API key — a secret token you generate once in the dashboard and send with every request, typically in a header. In ReSlug you create keys under Settings → API Keys and pass them in the X-Api-Key header. Pro accounts can hold up to 10 live keys, which matters more than it sounds: one key per integration means revoking a leaked CI key doesn't break your production backend.

Good APIs also support scopes — per-key permissions that limit what a key can do. ReSlug keys can be restricted to combinations like links:read, links:write, analytics:read, or qr:write. The principle of least privilege applies exactly as it does anywhere else:

• A dashboard widget that only displays click counts needs analytics:read and nothing else.
• A marketing automation that creates campaign links needs links:write, but not domain or bio-page access.
• Reserve full-access keys for trusted backend services, and rotate them on a schedule.

Your first request: create a short link

Creating a link is a single POST. With curl, the whole thing looks like this:

curl -X POST https://api.reslug.com/api/links \
  -H "X-Api-Key: $RESLUG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationUrl": "https://example.com/spring-sale?utm_source=newsletter&utm_medium=email&utm_campaign=spring-sale-2026",
    "customSlug": "spring-sale"
  }'

The response is JSON containing the new link — its short URL, ID, and creation metadata. The same call from Node.js with fetch (no SDK required):

const res = await fetch('https://api.reslug.com/api/links', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.RESLUG_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    destinationUrl: 'https://example.com/spring-sale',
    customSlug: 'spring-sale',
  }),
})
if (!res.ok) throw new Error(`ReSlug API error: ${res.status}`)
const link = await res.json()

Two fields do most of the work. destinationUrl is the long URL the short link redirects to — send it fully encoded, including any campaign parameters. customSlug is optional; omit it and the API generates a random slug, set it and you get a readable branded path. If you want a feel for what makes a good slug before you script it, the slug generator shows the conventions interactively.

Automation patterns that come up constantly

Bulk campaign links with UTM parameters

The most common integration: a script that takes a list of ad variants, regions, or email segments, builds a UTM-tagged destination URL for each, and creates one short link per row. The naming discipline that matters in a UTM builder matters double in code — lowercase values, a shared vocabulary for source and medium — because a bug in your script misnames a thousand links instead of one. Build the query string with proper encoding (a query string builder shows the expected output) rather than string concatenation.

A short link and QR code per physical asset

Print campaigns, packaging, table tents, and event badges each want their own short link so scans are attributable per location or per item. The pattern: create the link via the API, then generate a QR code that encodes the short URL. Because the QR code contains the short link rather than the destination, you can re-point the destination later without reprinting anything — how that works is covered in how QR codes work.

Links created by your product on behalf of users

SaaS products often generate share links, referral links, or invite links at signup time. Calling a link API from your backend keeps those URLs short and trackable, and link-level analytics tell you which users' shares actually drive traffic. Keep the API call out of the request path where you can — create the link asynchronously and store the result — so a slow third-party response never blocks your own user.

Rate limits and error handling

Every serious API enforces a rate limit; ReSlug allows 200 requests per minute per account. For bulk jobs that ceiling is the design constraint: a 10,000-link import at full speed takes 50 minutes, not 5 seconds. The standard playbook:

• Respect `429 Too Many Requests`. Back off and retry with exponential delay plus jitter rather than hammering the endpoint.
• Throttle proactively. Spacing bulk requests ~350 ms apart keeps you safely under 200/min without ever hitting the limit.
• Make retries safe. If a request times out, you may not know whether the link was created. Check for an existing link with the same customSlug before retrying, or design slugs so a duplicate-slug error on retry is your idempotency signal.
• Handle validation errors (`400`) differently from auth errors (`401`/`403`). A bad destination URL is a data problem to log and skip; an invalid key should stop the whole job and alert you.

Log the response body on failure, not just the status code — a good API tells you which field failed validation and why, and that message is the difference between a five-minute fix and an evening of guessing.

Choosing a URL shortener API

If you are still picking a platform, evaluate the API as a product in its own right. The checklist that separates usable from frustrating:

• Honest pricing for API access. Some providers meter API requests aggressively or gate the API behind enterprise tiers. ReSlug includes the API in Pro at $6.6/month annual; Bitly's free tier caps you at 1,000 requests a month.
• Scoped keys, so one integration can't act beyond its job.
• Custom domain support via the API, if branded links matter to you.
• Analytics endpoints, not just link CRUD — otherwise you're scraping your own dashboard.
• Real documentation with a try-it-now reference, request/response examples, and documented error shapes.

The ReSlug vs Bitly comparison shows how API allowances differ between platforms, and the best Bitly alternatives guide surveys the wider field — API access is one of the axes where the platforms differ most.