Create Link

Request model: LinkCreateRequest

link is required. Select one address mode: a managed subdomain or an owned, verified custom_domain. New integrations should use reference; code remains a legacy alias.

{
  "subdomain": "yourbrand",
  "reference": "summer-campaign",
  "link": "https://example.com/landing",
  "fallback_url": "https://example.com/download",
  "apn": "com.example.app",
  "ios_store_url": "https://apps.apple.com/app/id000000000",
  "active_from": "2026-08-21",
  "expires_at": "2026-09-30",
  "click_limit": 10000,
  "parameters": [{ "name": "utm_source", "value": "newsletter" }],
  "device_targets": [{ "device": "android", "url": "https://example.com/android" }]
}

cURL example

curl --request POST 'https://a.zq.tn/api/v1/links' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --data '{"subdomain":"yourbrand","reference":"summer-campaign","link":"https://example.com/landing"}'

JavaScript server example

const response = await fetch('https://a.zq.tn/api/v1/links', {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'Content-Type': 'application/json',
    'X-Api-Key': process.env.ZQ_API_KEY,
  },
  body: JSON.stringify({
    subdomain: 'yourbrand',
    reference: 'summer-campaign',
    link: 'https://example.com/landing',
  }),
});
const payload = await response.json();
if (!response.ok) throw new Error(payload.message ?? `HTTP ${response.status}`);
console.log(payload.short_link);

Response model: LinkCreateResponse

{
  "link": {
    "id": 123,
    "managed_subdomain": "yourbrand",
    "code": "summer-campaign",
    "destination_url": "https://example.com/landing",
    "clicks": 0,
    "is_anonymous": false
  },
  "short_link": "https://yourbrand.zq.tn/summer-campaign"
}

Anonymous variant

POST /createlink returns a one-time claim_key, anonymous_claim, and short_link under https://zq.tn/s/. The server allocates a random, case-sensitive Base62 reference of at least 10 characters. Store the claim secret immediately; it cannot be retrieved again. Each guest address stays active for 7 days, and the public widget permits up to three guest creations per browser session.

Claim contract

Claim keeps the exact guest reference and assigns it to the account; no replacement reference is generated. Under Free, automatic references use 10 characters and the claimed address redirects until 30 days or 30 redirects, whichever happens first. Starter uses 6-character automatic references or a custom alias; Pro uses 4-character automatic references or a custom alias. A reference already served is never reassigned to another owner.

Safety and conflicts

An unavailable hostname or reference returns 409. Invalid, foreign, pending, or unverified domains return 422. Plan restrictions may return 403 or 422. A destination classified as local, private, reserved, or otherwise unsafe is quarantined and cannot redirect until an authorized review releases it.