REST API Reference

Quickstart

1. Get your API key from /account → API Keys
2. Send your first request using one of the examples below
3. Get fast responses via Cloudflare edge POPs in Jeddah + Riyadh (≈20-40ms)

Authentication

Every request must carry your key in an HTTP header:

X-API-Key: zlk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Alternatively: Authorization: Bearer zlk_...

Base URL

https://zaye.cc/api/v1

Rate Limits

When exceeded: 429 Too Many Requests. Read header X-RateLimit-Remaining

Endpoints

POST /api/v1/links

Create a new short link.

Body (JSON):

{
  "url": "https://example.com/long-url",       // required
  "alias": "my-link",                           // optional — custom alias
  "expires_at": "2026-06-01T00:00:00Z",         // optional
  "password": "secret123",                      // optional
  "tags": ["campaign-2026", "ramadan"],         // optional
  "utm": {                                       // optional — appended to URL
    "source": "newsletter",
    "medium": "email",
    "campaign": "ramadan"
  }
}

Response (201):

{
  "ok": true,
  "data": {
    "id": "lnk_a1b2c3d4",
    "short_url": "https://zaye.cc/my-link",
    "long_url": "https://example.com/long-url",
    "created_at": "2026-05-19T11:30:00Z",
    "expires_at": "2026-06-01T00:00:00Z"
  }
}

GET /api/v1/links/:id

Get details of a specific link.

GET /api/v1/links

List all your links (paginated).

Query params:

• page — default 1
• limit — default 20, max 100
• tag — filter by tag

PATCH /api/v1/links/:id

Update a link (destination, expiration, password, tags).

DELETE /api/v1/links/:id

Delete a link (soft delete — recoverable within 14 days).

GET /api/v1/links/:id/analytics

Detailed analytics for a link.

Response:

{
  "ok": true,
  "data": {
    "total_clicks": 1247,
    "unique_clicks": 892,
    "by_country": [
      { "code": "SA", "clicks": 850 },
      { "code": "AE", "clicks": 180 }
    ],
    "by_device": { "mobile": 920, "desktop": 280, "tablet": 47 },
    "by_referrer": [...],
    "by_day": [...],
    "by_hour": [...]
  }
}

Full Examples

cURL

curl -X POST https://zaye.cc/api/v1/links \
  -H "X-API-Key: zlk_yourkey" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/long", "alias": "promo"}'

JavaScript (Node / Browser)

const res = await fetch('https://zaye.cc/api/v1/links', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ZLK_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com/long',
    alias: 'promo',
  }),
});
const { data } = await res.json();
console.log(data.short_url); // https://zaye.cc/promo

Python

import os, requests

res = requests.post(
    'https://zaye.cc/api/v1/links',
    headers={'X-API-Key': os.environ['ZLK_API_KEY']},
    json={'url': 'https://example.com/long', 'alias': 'promo'},
)
data = res.json()['data']
print(data['short_url'])  # https://zaye.cc/promo

PHP

$ch = curl_init('https://zaye.cc/api/v1/links');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'X-API-Key: ' . getenv('ZLK_API_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'url' => 'https://example.com/long',
    'alias' => 'promo',
  ]),
]);
$result = json_decode(curl_exec($ch), true);
echo $result['data']['short_url'];

Error Codes

Every error response has the shape:

{ "ok": false, "error": "Human readable AR/EN", "message_en": "English version", "code": "ERROR_CODE", "field": "optional" }

Webhooks (soon)

We will launch webhooks for events: click, expiration, limit-reached. Register interest at /contact.