Skip to content

Support center

Developer Docs.

The SwiftURL API is a REST API for creating branded short links, reading analytics and receiving signed webhooks. Authenticate with an API key sent as a bearer token; API access is included from the Pro plan, and the same safety checks apply whether a person or a script creates a link.

API reference OpenAPI 3.1 spec
POST /api/v1/links201 Created
curl -X POST https://app.swifturl.co/api/v1/links \
  -H "Authorization: Bearer $SWIFTURL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationUrl": "https://example.com/summer-sale",
    "slug": "summer24",
    "utmSource": "instagram"
  }'
Browse help and docs

Start here

Authentication

Requests to /api/v1/* accept an API key or a signed-in browser session. Create keys in the dashboard under Settings → API keys. Each key starts with ql_live_, belongs to one workspace, has read or read and write access, and is shown only once when created.

Send the key as a bearer token in the Authorization header:

GET/api/v1/links
curl https://app.swifturl.co/api/v1/links \
  -H "Authorization: Bearer ql_live_your_key_here"

An API key already belongs to one workspace, so it needs no workspace header, and a read key cannot make write calls. Requests from a signed-in session follow your role; if you belong to more than one workspace, set the x-workspace-id header to choose one, otherwise your default membership is used.

Create a link

Links are safety-checked before they are created. A destination that fails a blocking check, such as Google Web Risk, is rejected with a 422 and the reason.

POST/api/v1/links
curl -X POST https://app.swifturl.co/api/v1/links \
  -H "Authorization: Bearer ql_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "destinationUrl": "https://example.com/sale", "slug": "spring-sale" }'

POST /api/v1/links supports an Idempotency-Key header, so a retried request will not create a duplicate link.

What you can call

What you can call
ResourceMethodsEndpoints
Links GETPOST /api/v1/links/links/{id}/links/import
Analytics GET /api/v1/analytics?range=7|30|90plus geo, campaign, link and realtime breakdowns
Campaigns GETPOST /api/v1/campaigns/campaigns/{id}
Webhooks GETPOST /api/v1/webhooks/webhooks/{id}delivery history
UTM presets GETPOST /api/v1/utm-presets/utm-presets/{id}
Custom domains GETPOST /api/v1/domainsverify and configure
API keys GETPOST /api/v1/api-keys/api-keys/{id}

Parameters, responses and schemas for each call are in the API reference.

Webhooks

Webhooks are included from the Business plan. Register endpoints to receive events such as a link's health changing. Each delivery is signed with HMAC-SHA256 so you can verify it came from SwiftURL, and your signing secret is stored encrypted at rest. Deliveries are logged with retry tracking.

Manage endpoints under Settings → Webhooks, or via POST /api/v1/webhooks. Verify a delivery by recomputing the HMAC of the raw request body with your endpoint's signing secret and comparing it to the signature header.

The Webhooks screen in SwiftURL settings: an Endpoints panel with an Add webhook button, and a Signature verification panel explaining the HMAC-SHA256 signature and timestamp headers with a Node.js verification example.
Settings → Webhooks in the app, with the signature verification steps shown next to your endpoints.

Rate limits & errors

API calls are rate limited to keep the platform reliable. On errors, the API returns a generic message with the relevant HTTP status; detailed diagnostics are logged server-side, not returned to clients.

Need something that isn't here yet? Reach us at support@swifturl.co.