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 URL shortener API lets you create branded short links, deep links, and analytics programmatically, for India and beyond. Every link created through the API is automatically verified against Google Web Risk, adult-content filters, GDPR / India DPDP PII checks, and reachability before it goes live.

Base URL https://app.swifturl.co OpenAPI 3.1 spec

Authentication

All /api/v1/* endpoints require a session cookie from the SwiftURL dashboard. Programmatic API-key auth is on the roadmap.

Rate limits

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

POST links · 60 / hr
GET links · 600 / hr
DELETE links · 60 / hr

Idempotency

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

Endpoints

POST /links GET /links GET /links/{id} DELETE /links/{id} POST /track/open GET /health

Schemas

CreateLinkRequest Link LinkListResponse ComplianceFinding

Endpoints

POST/api/v1/linksCreate a link

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

Name	Type		Description
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

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" }

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.

GET/api/v1/linksList links

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

Query parameters

Name	Type		Description
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.

GET/api/v1/links/{linkId}Retrieve a link

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

Name	Type		Description
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.

DELETE/api/v1/links/{linkId}Delete a link

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

Name	Type		Description
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.

POST/api/v1/track/openRedeem a deferred deep link

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

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

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).

SETTINGSDeep-link domain 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:

Setting	Field	What it does
Deep View	deepViewEnabled	Serves a branded preview page (title and image) with "Open in app" and "Get the app" when the app is not installed.
Deferred deep linking	deferredDeepLink	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.

GET/api/healthHealth check

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

Responses

200

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

Schemas

CreateLinkRequest

Field	Type		Description
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

Field	Type	Description
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

Field	Type	Description
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

Field	Type	Description
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).

Need something that isn't here yet? Reach us at support@swifturl.co, or explore the interactive reference and full spec linked at the top.