Gozi.to

API

لینک‌های کوتاه را از اسکریپت‌ها و برنامه‌ها بسازید و مدیریت کنید. API رایگان است. در داشبورد خود، زیر بخش کلیدهای API، یک کلید بسازید و آن را به‌صورت توکن Bearer بفرستید.

احراز هویت

Authorization: Bearer gz_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

کلیدها فقط یک بار نشان داده می‌شوند. با آن‌ها مثل گذرواژه رفتار کنید: هر کسی کلید شما را داشته باشد می‌تواند در حساب شما لینک بسازد و ویرایش کند. کلید لو رفته را از داشبورد باطل کنید.

محدودیت‌ها

ساختن یک لینک

curl -X POST https://gozi.to/api/my/links \
  -H "Authorization: Bearer $GOZI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/launch", "code": "launch"}'

code اختیاری است (۴ تا ۳۲ حرف، رقم، - یا _). اگر ننویسیدش، یک کد تصادفی ۷ نویسه‌ای ساخته می‌شود. پاسخ 201:

{
  "link": {
    "code": "launch",
    "shortUrl": "https://gozi.to/launch",
    "url": "https://example.com/launch",
    "status": "active",
    "statusReason": null,
    "custom": true,
    "createdAt": 1790000000000,
    "expiresAt": null
  }
}

فهرست لینک‌ها

GET /api/my/links?limit=25&cursor=<nextCursor>&q=<search>&clicks=1

تازه‌ترین‌ها اول. برای گرفتن صفحهٔ بعد، nextCursor صفحهٔ قبل را بفرستید. clicks=1 شمار کل کلیک‌های انسانی را هم اضافه می‌کند.

گرفتن، ویرایش، حذف

GET    /api/my/links/{code}
PATCH  /api/my/links/{code}   {"url": "https://new.example"}  or  {"status": "disabled" | "active"}
DELETE /api/my/links/{code}

آمار

GET /api/my/links/{code}/stats

کلیک‌های انسانی ۹۰ روز گذشته و کل دوران، کلیک در هر روز، و کشورها، ارجاع‌دهنده‌ها، دستگاه‌ها، مرورگرها و سیستم‌عامل‌های برتر را برمی‌گرداند. ربات‌ها و پیش‌نمایش‌های لینک (Slack، WhatsApp و مانند آن) جداگانه در botClicks شمرده می‌شوند. نتیجه‌ها حدود ۵ دقیقه کش می‌شوند.

خطاها

خطاها از کدهای وضعیت HTTP و یک بدنهٔ JSON استفاده می‌کنند:

{ "error": { "code": "slug_taken", "message": "That custom link is already taken." } }

توصیف ماشین‌خوان همهٔ endpointها در /openapi.json هست.