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 uses the same model but returns a one-time claim_key and anonymous_claim. Store that secret immediately; it cannot be retrieved again.

Conflicts

An unavailable hostname or reference returns 409. Invalid, foreign, pending, or unverified domains return 422. Plan restrictions may return 403 or 422.