{"openapi":"3.0.3","info":{"title":"Kokli API","version":"1.1.0","description":"API عمومی کوکلی (kok.li) برای ساخت و مدیریت لینک کوتاه، آمار کلیک و QR کد. کلید را از داشبورد (بخش کلیدهای API) بسازید و در هدر Authorization: Bearer ارسال کنید. هر کلید فقط به scopeهای انتخاب‌شده دسترسی دارد."},"servers":[{"url":"https://kok.li/api/v1"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"kk_live_…","description":"Scopes: {\"links:read\":\"خواندن لینک‌ها\",\"links:write\":\"ساخت و ویرایش لینک\",\"links:delete\":\"حذف لینک\",\"analytics:read\":\"مشاهده آمار کلیک\",\"qr:read\":\"دریافت QR کد\",\"account:read\":\"اطلاعات حساب و مصرف\"}"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"پیام فارسی قابل نمایش"},"code":{"type":"string","enum":["missing_api_key","invalid_api_key","key_expired","key_disabled","ip_not_allowed","api_access_denied","insufficient_scope","rate_limited","validation_error","not_found","alias_taken","url_rejected","limit_reached","quota_exceeded","error"]}}},"CreatedLink":{"type":"object","properties":{"code":{"type":"string"},"alias":{"type":"string"},"shortUrl":{"type":"string"},"longUrl":{"type":"string"},"clicks":{"type":"integer"},"scanStatus":{"type":"string","enum":["pending","clean","review","blocked"]},"expiresAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"Link":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"shortUrl":{"type":"string"},"longUrl":{"type":"string"},"clicks":{"type":"integer"},"status":{"type":"string","enum":["active","paused","archived","blocked"]},"scanStatus":{"type":"string","enum":["pending","clean","review","blocked"]},"tags":{"type":"array","items":{"type":"string"}},"folder":{"type":"string","nullable":true},"maxClicks":{"type":"integer","nullable":true},"fallbackUrl":{"type":"string","nullable":true},"passwordProtected":{"type":"boolean"},"utm":{"type":"object","additionalProperties":{"type":"string","nullable":true}},"expiresAt":{"type":"string","format":"date-time","nullable":true},"lastClickedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"Analytics":{"type":"object","properties":{"range":{"type":"integer"},"from":{"type":"string"},"to":{"type":"string"},"daily":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"clicks":{"type":"integer"},"uniques":{"type":"integer"}}}},"totals":{"type":"object","properties":{"clicks":{"type":"integer"},"uniques":{"type":"integer"}}},"breakdown":{"type":"object","nullable":true,"description":"فقط در پلن‌های دارای آمار پیشرفته"}}}}},"paths":{"/me":{"get":{"summary":"اطلاعات حساب، کلید و مصرف","security":[{"bearerAuth":["account:read"]}],"responses":{"200":{"description":"OK"},"401":{"description":"کلید نامعتبر، منقضی یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope، IP، پلن یا مسدودسازی توسط ادمین)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"سقف نرخ یا سهمیهٔ ماهانه","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/links":{"get":{"summary":"لیست لینک‌ها","security":[{"bearerAuth":["links:read"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100}},{"name":"q","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["active","paused","archived","blocked"]}},{"name":"tag","in":"query","schema":{"type":"string"}},{"name":"folder","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"links":{"type":"array","items":{"$ref":"#/components/schemas/Link"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"description":"کلید نامعتبر، منقضی یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope، IP، پلن یا مسدودسازی توسط ادمین)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"سقف نرخ یا سهمیهٔ ماهانه","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"ساخت لینک کوتاه","security":[{"bearerAuth":["links:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["longUrl"],"properties":{"longUrl":{"type":"string","example":"https://example.com/very/long/url"},"alias":{"type":"string","description":"کد اختصاصی ۶ تا ۳۲ کاراکتر (حروف، عدد، - و _)"},"utmSource":{"type":"string"},"utmMedium":{"type":"string"},"utmCampaign":{"type":"string"},"utmTerm":{"type":"string"},"utmContent":{"type":"string"},"expireIn":{"type":"string","enum":["1d","3d","7d","14d","30d","90d","never"]},"expiresAt":{"type":"string","format":"date-time"},"password":{"type":"string"}}}}}},"responses":{"201":{"description":"ساخته شد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedLink"}}}},"400":{"description":"درخواست نامعتبر (validation_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید نامعتبر، منقضی یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope، IP، پلن یا مسدودسازی توسط ادمین)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"کد اختصاصی تکراری است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"آدرس مقصد به دلایل امنیتی رد شد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"سقف نرخ یا سهمیهٔ ماهانه","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/links/bulk":{"post":{"summary":"ساخت گروهی (حداکثر ۵۰ لینک)","security":[{"bearerAuth":["links:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["links"],"properties":{"links":{"type":"array","maxItems":50,"items":{"type":"object","required":["longUrl"],"properties":{"longUrl":{"type":"string","example":"https://example.com/very/long/url"},"alias":{"type":"string","description":"کد اختصاصی ۶ تا ۳۲ کاراکتر (حروف، عدد، - و _)"},"utmSource":{"type":"string"},"utmMedium":{"type":"string"},"utmCampaign":{"type":"string"},"utmTerm":{"type":"string"},"utmContent":{"type":"string"},"expireIn":{"type":"string","enum":["1d","3d","7d","14d","30d","90d","never"]},"expiresAt":{"type":"string","format":"date-time"},"password":{"type":"string"}}}}}}}}},"responses":{"201":{"description":"حداقل یک لینک ساخته شد"},"400":{"description":"درخواست نامعتبر (validation_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید نامعتبر، منقضی یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope، IP، پلن یا مسدودسازی توسط ادمین)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"سقف نرخ یا سهمیهٔ ماهانه","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/links/{code}":{"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"},"description":"کد لینک کوتاه (مثل abc123)"}],"get":{"summary":"دریافت یک لینک","security":[{"bearerAuth":["links:read"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Link"}}}},"401":{"description":"کلید نامعتبر، منقضی یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope، IP، پلن یا مسدودسازی توسط ادمین)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"پیدا نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"ویرایش لینک (PUT هم پذیرفته می‌شود)","security":[{"bearerAuth":["links:write"]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"longUrl":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"folder":{"type":"string","nullable":true},"maxClicks":{"type":"integer","nullable":true},"fallbackUrl":{"type":"string","nullable":true},"password":{"type":"string","nullable":true},"expireIn":{"type":"string"},"expiresAt":{"type":"string"},"deviceTargets":{"type":"object","properties":{"ios":{"type":"string"},"android":{"type":"string"},"desktop":{"type":"string"}}}}}}}},"responses":{"200":{"description":"OK"},"400":{"description":"درخواست نامعتبر (validation_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید نامعتبر، منقضی یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope، IP، پلن یا مسدودسازی توسط ادمین)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"پیدا نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"آدرس مقصد به دلایل امنیتی رد شد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"حذف لینک و آمار آن","security":[{"bearerAuth":["links:delete"]}],"responses":{"200":{"description":"OK"},"401":{"description":"کلید نامعتبر، منقضی یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope، IP، پلن یا مسدودسازی توسط ادمین)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"پیدا نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/links/{code}/stats":{"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"},"description":"کد لینک کوتاه (مثل abc123)"}],"get":{"summary":"آمار کلیک یک لینک","security":[{"bearerAuth":["analytics:read"]}],"parameters":[{"name":"range","in":"query","schema":{"type":"integer","enum":[7,10,14,30,90,180,365],"default":10}},{"name":"from","in":"query","schema":{"type":"string","format":"date"},"description":"YYYY-MM-DD (همراه to)"},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"description":"YYYY-MM-DD (همراه from)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Analytics"}}}},"401":{"description":"کلید نامعتبر، منقضی یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope، IP، پلن یا مسدودسازی توسط ادمین)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"پیدا نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/links/{code}/qr":{"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"},"description":"کد لینک کوتاه (مثل abc123)"}],"get":{"summary":"تصویر QR لینک","security":[{"bearerAuth":["qr:read"]}],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["png","svg"],"default":"png"}},{"name":"size","in":"query","schema":{"type":"integer","minimum":64,"maximum":1024,"default":320}},{"name":"color","in":"query","schema":{"type":"string","example":"000000"}},{"name":"bgColor","in":"query","schema":{"type":"string","example":"ffffff"}},{"name":"margin","in":"query","schema":{"type":"integer","minimum":0,"maximum":10}},{"name":"ecc","in":"query","schema":{"type":"string","enum":["L","M","Q","H"]}}],"responses":{"200":{"description":"تصویر","content":{"image/png":{},"image/svg+xml":{}}},"401":{"description":"کلید نامعتبر، منقضی یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope، IP، پلن یا مسدودسازی توسط ادمین)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"پیدا نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/analytics":{"get":{"summary":"آمار کل حساب","security":[{"bearerAuth":["analytics:read"]}],"parameters":[{"name":"range","in":"query","schema":{"type":"integer","enum":[7,10,14,30,90,180,365],"default":10}},{"name":"from","in":"query","schema":{"type":"string","format":"date"},"description":"YYYY-MM-DD (همراه to)"},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"description":"YYYY-MM-DD (همراه from)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Analytics"}}}},"401":{"description":"کلید نامعتبر، منقضی یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope، IP، پلن یا مسدودسازی توسط ادمین)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}