SwiftURL is a branded URL shortener and link management platform. Create short links on your own domain with automatic SSL, track clicks with real-time analytics and AI Insights, route mobile users into your app with deep linking, and keep every link accountable with safety checks, audit logs, and India-ready DLT/TRAI and DPDP compliance. Built for marketing agencies and enterprise teams, especially those running high-volume SMS and WhatsApp outreach. Explore features, pricing, security, or the API.

SwiftURL API.

v1.0.0

The SwiftURL API is a REST API for creating and managing branded short links and deep links from your own code. Authenticate with an API key sent as a bearer token. Every link it creates passes the same checks as the app before it goes live: Google Web Risk, the adult content filter, private IP and shortener-chain blocks and a reachability check, with flags for HTTPS, personal data in URL parameters, domain age and URL validity.

Base URL https://app.swifturl.co

OpenAPI 3.1 spec

Authentication

Send an API key as a bearer token: Authorization: Bearer ql_live_…. Create keys under Settings → API keys; each belongs to one workspace and has read or read and write access. Requests from a signed-in dashboard session also work. API access is included from the Pro plan. Authentication guide

Rate limits

Per-workspace, sliding window. State returned in X-RateLimit-* headers.

POSTlinks60 / hr
GETlinks600 / hr
GETQR codes300 / min
DELETElinks60 / hr

Idempotency

POST endpoints accept an Idempotency-Key (UUID v4). Reusing a key within 24h replays the original response with X-Idempotent-Replayed: true.

On this page

Endpoints

Create a link (link to this section)

POST /api/v1/links

Creates a new short link. The destination URL is verified against safety and compliance rules before the link goes live. Returns 422 with compliance_failed if any hard-block rule is triggered.

Headers

x-workspace-id string optional

Target workspace. Falls back to the user's default workspace.
Idempotency-Key uuid optional

UUID v4 that makes the request idempotent for 24 hours. Safe to retry on network failure.

Request body required

A CreateLinkRequest.

Responses

201
Link created. Returns a Link plus X-RateLimit-* headers and any non-blocking warnings.
401
Missing or invalid authentication.
404
Resource not found or access denied.
422
Validation failed, or a compliance check blocked the link (ComplianceFinding list).
429
Rate limit exceeded. See Retry-After.

Request

POST /api/v1/links
# Content-Type: application/json
{
  "destinationUrl": "https://example.com/summer-sale",
  "slug": "summer24",
  "title": "Summer Sale 2024",
  "tags": ["campaign", "summer"],
  "utmSource": "instagram",
  "utmMedium": "social",
  "utmCampaign": "summer-sale-2024"
}

Response 201

{
  "id": "clx1234abcdef",
  "slug": "summer24",
  "shortUrl": "https://go.acme.com/summer24",
  "destinationUrl": "https://example.com/summer-sale",
  "status": "ACTIVE",
  "complianceStatus": "APPROVED",
  "createdAt": "2026-07-16T09:30:00.000Z",
  "warnings": []
}

Response 422

{
  "error": "compliance_failed",
  "message": "This link did not pass our safety and compliance checks.",
  "findings": [
    {
      "ruleId": "web_risk",
      "ruleName": "Google Web Risk",
      "severity": "CRITICAL",
      "passed": false,
      "message": "This URL is flagged as phishing by Google Web Risk.",
      "hint": null
    }
  ]
}

List links (link to this section)

GET /api/v1/links

Returns a paginated list of links for the authenticated workspace, ordered by creation date descending.

Query parameters

cursor string optional

Pagination cursor: the id of the last item from the previous page.
limit integer optional

Items per page. Min 1, max 100, default 20.
q string optional

Fuzzy search across slug, destination URL and title (case-insensitive).
slug string optional

Exact slug match (not fuzzy). Returns the single matching link in items, or an empty list. Useful for resolving a short URL you hold to its id.
tag string optional

Filter by tag (exact match).

Responses

200
A LinkListResponse with items, total, nextCursor and hasMore.
401
Missing or invalid authentication.
429
Rate limit exceeded.

Request

GET /api/v1/links?limit=20&tag=campaign

Response200

{
  "items": [
    {
      "id": "clx1234abcdef",
      "slug": "summer24",
      "shortUrl": "https://go.acme.com/summer24",
      "destinationUrl": "https://example.com/summer-sale",
      "title": "Summer Sale 2024",
      "tags": ["campaign", "summer"],
      "status": "ACTIVE",
      "complianceStatus": "APPROVED",
      "clicks": 0,
      "createdAt": "2026-07-16T09:30:00.000Z"
    }
  ],
  "total": 1,
  "hasMore": false
}

Retrieve a link (link to this section)

GET /api/v1/links/{linkId}

Returns a single link by ID, scoped to the authenticated workspace. Same object shape as an item in List links. To look one up by slug instead, use GET /api/v1/links?slug=<slug>.

Path parameters

linkId string required

The unique ID of the link to retrieve.

Responses

200
Returns { "link": { … } } with the link's fields.
401
Missing or invalid authentication.
404
Link not found or access denied.

Request

GET /api/v1/links/clx1234abcdef

Response200

{
  "link": {
    "id": "clx1234abcdef",
    "slug": "summer24",
    "shortUrl": "https://go.acme.com/summer24",
    "destinationUrl": "https://example.com/summer-sale",
    "status": "ACTIVE",
    "complianceStatus": "APPROVED",
    "createdAt": "2026-07-16T09:30:00.000Z"
  }
}

Get a link's QR code (link to this section)

GET /api/v1/links/{linkId}/qr

Returns the link's QR code as a PNG or SVG image. The code encodes the short URL plus a ?qr marker, so scans are counted as QR scans in analytics; the marker is never passed on to the destination. On Pro and above the code uses the link's saved colors and your organization's logo; on Free it is the standard black on white code. Needs an API key with read access, or a dashboard session. See QR codes.

Path parameters

linkId string required

The unique ID of the link.

Query parameters

format string optional

png (default) or svg. SVG scales to any size.
size integer optional

PNG width and height in pixels. Min 128, max 2048, default 1024. Values outside the range are clamped.
download boolean optional

1 or true adds a Content-Disposition: attachment header with a file name such as qr-summer24-2048.png.

Responses

200
The image (image/png or image/svg+xml). X-QR-Content holds the exact URL the code encodes.
401
Missing or invalid authentication.
403
The API key does not have the read scope.
404
Link not found or access denied.
422
format is not png or svg.
429
Rate limit exceeded.

Request

GET /api/v1/links/clx1234abcdef/qr?format=png&size=2048&download=1
# Authorization: Bearer ql_live_...

Response200

HTTP/1.1 200 OK
Content-Type: image/png
Content-Disposition: attachment; filename="qr-summer24-2048.png"
X-QR-Content: https://go.acme.com/summer24?qr

<PNG bytes>

Delete a link (link to this section)

DELETE /api/v1/links/{linkId}

Soft-deletes a link. The record is preserved for audit purposes but the short URL immediately stops resolving. The slug is freed and can be reused.

Path parameters

linkId string required

The unique ID of the link to delete.

Responses

200
Link deleted. Returns { "ok": true }.
401
Missing or invalid authentication.
404
Link not found or access denied.
429
Rate limit exceeded.

Request

DELETE /api/v1/links/clx1234abcdef

Response200

{ "ok": true }

Redeem a deferred deep link (link to this section)

POST /api/v1/track/open

Redeems a deferred deep linking token on the app's first launch after a store install, and returns the original link target so the app can route to the right screen. The token is the credential, so no API key is required. Tokens are opaque, single-use, and short-lived (default 1 hour). Recover the token from the Play Install Referrer on Android or the user-initiated clipboard on iOS. See Deferred Deep Linking.

Request body required

Responses

200
Token redeemed. Returns { "destination", "deepLinkPath", "linkId" } so the app can open the exact target.
404
Returns { "error": "not_found" } when the token is unknown, expired, or already used (single-use).

Request

POST /api/v1/track/open
# Content-Type: application/json
{
  "token": "<opaque token>"
}

Response 200

{
  "destination": "https://example.com/summer-sale",
  "deepLinkPath": "/products/summer",
  "linkId": "clx1234abcdef"
}

Response 404

{ "error": "not_found" }

Deep-link domain settings (link to this section)

SETTINGS

Deep linking behaviour is configured per domain in Settings→Domains→Mobile app deep linking, not through the API. Two toggles control the no-app path:

deepViewEnabled Deep View

Serves a branded preview page (title and image) with "Open in app" and "Get the app" when the app is not installed.
deferredDeepLink Deferred deep linking

Mints the one-time token on "Get the app" so the target survives the store install and is recoverable via /track/open.

The same screen holds the app identity (Team ID, Bundle ID, package name, SHA-256 fingerprints, URI scheme) used to generate the apple-app-site-association and assetlinks.json association files served on your domain.

Health check (link to this section)

GET /api/health

Returns 200 if the API is reachable. Used by uptime monitors.

Responses

200
Service is healthy. Returns { "ok": true }.

Request

GET /api/health

Response200

{ "ok": true }

Schemas

CreateLinkRequest

destinationUrl string · uri required

Redirect target. Checked against Web Risk, adult TLDs, shortener chains and reachability.
slug string optional

Custom short code (1-64, [a-zA-Z0-9_-]). Auto-generated (6 chars) if omitted.
title string optional

Human-readable label shown in the dashboard (max 255).
description string optional

Longer internal description (max 1000).
tags string[] optional

Up to 10 tags for filtering and organisation.
expiresAt date-time optional

ISO 8601 datetime after which the link stops resolving.
expiredRedirectUrl string · uri optional

Where to redirect after expiresAt.
utmSource / utmMedium / utmCampaign / utmTerm / utmContent string optional

UTM parameters appended to the destination (max 100 each).
ogTitle / ogDescription / ogImageUrl string optional

Open Graph overrides for social previews.

Link

id string

Unique link ID (CUID).
slug string

Short code.
shortUrl string · uri

Full short URL ready to share.
destinationUrl string · uri

Where the link redirects.
status enum

ACTIVE · ARCHIVED
complianceStatus enum

APPROVED · NOT_REQUIRED · PENDING_REVIEW · REJECTED · BLOCKED
createdAt date-time

Creation timestamp.
warnings ComplianceFinding[]

Non-blocking compliance warnings flagged for your attention.

LinkListResponse

items LinkListItem[]

Links on this page (id, slug, shortUrl, destinationUrl, title, tags, status, complianceStatus, clicks, createdAt).
total integer

Total links in the workspace.
nextCursor string

Pass as cursor for the next page. Absent on the last page.
hasMore boolean

Whether more pages are available.

ComplianceFinding

ruleId string

e.g. web_risk.
ruleName string

e.g. Google Web Risk.
severity enum

CRITICAL · ERROR · WARNING · INFO
passed boolean

Whether this rule passed.
message string

Human-readable explanation of the finding.
hint string

Actionable guidance for the user (nullable).