مستندات API

API هوپ ساده و JSON است. ساخت لینک بدون کلید هم ممکن است (با محدودیت نرخ)؛ برای مدیریت لینک‌ها و آمار خصوصی، از کلید API حساب رایگان خود استفاده کنید.

آدرس پایه: https://h0p.ir/api/v1   احراز هویت: هدر Authorization: Bearer h0p_xxx یا پارامتر key. بدنه درخواست می‌تواند form یا JSON باشد.

ساخت لینک کوتاه

POST /api/v1/shorten

پارامتر	توضیح
url	الزامی — آدرس مقصد
code	نام دلخواه (۳ تا ۴۰ کاراکتر؛ حروف، عدد، - و _)
title	عنوان برای خودتان
password	رمز لینک
expires	تاریخ انقضا: 1405/07/30 یا 2026-10-22 (+ ساعت اختیاری 14:00، به وقت تهران)
max_clicks	سقف تعداد بازدید
public_stats	1 = آمار عمومی

curl -X POST https://h0p.ir/api/v1/shorten \
  -H "Authorization: Bearer h0p_YOUR_KEY" \
  -d "url=https://example.com/very/long/page" \
  -d "code=my-link" -d "title=Instagram bio"

{
  "ok": true,
  "link": {
    "code": "my-link",
    "short_url": "https://h0p.ir/my-link",
    "url": "https://example.com/very/long/page",
    "clicks": 0, "status": "active",
    "stats_url": "https://h0p.ir/my-link+",
    "qr_svg": "https://h0p.ir/my-link/qr.svg"
  }
}

بدون کلید هم می‌توانید POST /api/v1/shorten بزنید (۶۰ لینک در ساعت به‌ازای هر IP). در این حالت پاسخ یک manage_url هم دارد که تنها راه مدیریت آن لینک است.

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

GET /api/v1/links?page=1&per_page=50 — کلید الزامی.

آمار یک لینک

GET /api/v1/stats/{code}?days=30 — کلید مالک، یا بدون کلید اگر آمار لینک عمومی باشد.

{
  "ok": true,
  "link": { "code": "my-link", ... },
  "stats": {
    "clicks": 1280, "unique_visitors": 940, "bot_hits": 37, "today": 12, "last_7_days": 210,
    "daily": { "2026-09-01": 40, "2026-09-02": 55, ... },
    "hourly": { "09": 30, "10": 48, ... },
    "referrers": { "instagram.com": 700, "direct": 400, "t.me": 180 },
    "countries": { "IR": 1200, "DE": 40 },
    "devices": { "mobile": 1100, "desktop": 180 },
    "browsers": { "Chrome": 900, "Instagram": 300 },
    "os": { "Android": 800, "iOS": 300 }
  }
}

ویرایش لینک

POST /api/v1/links/{code} — همان پارامترهای ساخت به‌علاوه status (active | disabled). فقط فیلدهایی که می‌فرستید تغییر می‌کنند؛ password= خالی رمز را حذف می‌کند.

حذف لینک

DELETE /api/v1/links/{code} یا POST /api/v1/links/{code}/delete

مقصد یک لینک کوتاه (بدون شمارش کلیک)

GET /api/v1/expand/{code} — عمومی.

خطاها

همه پاسخ‌ها {"ok": false, "error": "..."} با کد HTTP مناسب: 401 کلید نامعتبر، 403 عدم دسترسی، 404 پیدا نشد، 422 ورودی نامعتبر، 429 محدودیت نرخ.

نمونه پایتون

import requests
r = requests.post("https://h0p.ir/api/v1/shorten",
    headers={"Authorization": "Bearer h0p_YOUR_KEY"},
    json={"url": "https://example.com/page", "title": "test"})
print(r.json()["link"]["short_url"])

نمونه جاوااسکریپت

const r = await fetch("https://h0p.ir/api/v1/shorten", {
  method: "POST",
  headers: {"Content-Type": "application/json", "Authorization": "Bearer h0p_YOUR_KEY"},
  body: JSON.stringify({url: "https://example.com/page"})
});
const {link} = await r.json();
console.log(link.short_url);