REST API
Jenga juu ya viungo vyako.

Utambulisho, eneo la kazi, mpango na kila haki ambayo mpango huo unabeba. Njia rahisi zaidi ya kuthibitisha tokeni na kugundua kile akaunti inaruhusiwa kufanya kabla ya kujaribu.

curl -H "X-API-KEY: YOUR_TOKEN" \
  https://letl.ink/api/v1/me

{
  "data": {
    "user": { "id": 1, "email": "[email protected]", "name": "You" },
    "workspace": { "id": 12, "name": "My Workspace", "block_bots": true },
    "plan": {
      "id": "growth",
      "name": "Growth",
      "limits": {
        "links": 200,
        "monthly_clicks": 100000,
        "custom_domains": 3,
        "qr_codes": 30,
        "retention_days": 365
      },
      "features": {
        "api": true,
        "webhooks": true,
        "integrations": true,
        "ai_access": false,
        "geo_analytics": false,
        "smart_link_types": true
      }
    },
    "base_domain": "letl.ink"
  }
}

Kiasi cha kila kiwango kilichotumika mwezi huu wa malipo. Kitumie kumwonya mteja kabla hajafikia kikomo cha mibofyo inayofuatiliwa — baada ya hapo uelekezaji bado hufanya kazi, lakini mibofyo huacha kurekodiwa.

{
  "data": {
    "links": { "used": 42, "limit": 200, "remaining": 158, "percent_used": 21.0 },
    "clicks_this_month": { "used": 8140, "limit": 100000, "remaining": 91860, "percent_used": 8.1 },
    "custom_domains": { "used": 1, "limit": 3, "remaining": 2, "percent_used": 33.3 },
    "qr_codes": { "used": 4, "limit": 30, "remaining": 26, "percent_used": 13.3 }
  },
  "meta": { "plan": "growth", "period": "2026-09" }
}

Vikoa maalum vya eneo la kazi na kama kila kimoja kimekamilisha uthibitishaji wa DNS. Vikoa vilivyothibitishwa pekee ndivyo vinaweza kutumika kama sehemu ya domain wakati wa kuunda kiungo.

Kila muunganisho ambao bidhaa inatoa, kama mpango wako unaujumuisha, kama eneo hili la kazi limeuunganisha, na jinsi uwasilishaji unavyoendelea — hali ya mwisho, hitilafu ya mwisho na idadi ya kushindwa mfululizo. Inafaa kwa kufuatilia maeneo mengi ya kazi.

Viungo katika eneo la kazi, na jumla ya mibofyo ikigawanywa kuwa all, ios, android na desktop. Viungo visivyo na mibofyo vimejumuishwa.

Vigezo vya hoja (query)

• domain string

  Weka kikomo kwa jina moja la mwenyeji. Liache ili kuorodhesha majina yote ya wenyeji katika eneo la kazi.

  Hiari
• search string

  Hulinganisha msimbo mfupi, kichwa na anwani lengwa.

  Hiari
• type string

  direct, utm, appstore, instagram, mobile au device.

  Hiari
• archived boolean

  Chaguo-msingi ni false. Tuma true ili kuorodhesha kumbukumbu badala yake.

  Hiari
• favorite boolean

  Weka kikomo kwa viungo vilivyowekewa nyota.

  Hiari
• sort string

  created_at (chaguo-msingi), clicks, short_code, title au updated_at.

  Hiari
• direction string

  asc au desc. Chaguo-msingi ni desc.

  Hiari
• limit integer

  1–200. Chaguo-msingi ni 50.

  Hiari
• offset integer

  Chaguo-msingi ni 0.

  Hiari
• start_date date

  YYYY-MM-DD. Huchuja jumla ya mibofyo kwa kipindi, si viungo vinavyorudishwa.

  Hiari
• end_date date

  YYYY-MM-DD, ikijumuisha.

  Hiari

curl -H "X-API-KEY: YOUR_TOKEN" \
  "https://letl.ink/api/v1/links?sort=clicks&limit=20"

{
  "data": [
    {
      "id": 49,
      "short_code": "spring",
      "domain": "letl.ink",
      "url": "https://letl.ink/spring",
      "destination": "https://shop.example.com/spring",
      "title": "Spring sale",
      "type": "utm",
      "archived": false,
      "favorite": true,
      "created_at": "2026-08-01T09:14:00+00:00",
      "updated_at": "2026-09-02T11:00:00+00:00",
      "clicks": { "all": 650, "ios": 180, "android": 210, "desktop": 260 },
      "total_clicks": 650,
      "device_limit": null,
      "utm": { "source": "twitter", "medium": "social", "campaign": "spring" },
      "split_test": {
        "variations": [
          { "name": "control", "url": "https://example.com/a", "weight": 2 },
          { "name": "variant-b", "url": "https://example.com/b", "weight": 1 }
        ]
      }
    }
  ],
  "meta": {
    "total": 42, "limit": 20, "offset": 0,
    "has_more": true, "next_offset": 20,
    "sort": "clicks", "direction": "desc",
    "date_range": { "start_date": null, "end_date": null },
    "domain": "all"
  }
}

Kiungo kimoja kwa kitambulisho, katika muundo ule ule ambao endpoint ya orodha hurudisha.

Unda kiungo kifupi. Acha short_code ili upate wa nasibu. Ikiwa anwani lengwa haina title tunapakua kichwa cha ukurasa chinichini.

Mwili wa JSON

• destination

  URL ya kuelekeza. Inahitajika kwa viungo vya direct na utm. original_url inakubalika kama jina mbadala.

  Inahitajika*
• short_code

  Hadi herufi 20: herufi, namba, vistari na mistari ya chini, bila kuanza wala kuishia na kitenganishi. Lazima iwe ya kipekee kwa kila hostname.

  Hiari
• title

  Jina linaloonyeshwa kwenye dashibodi.

  Hiari
• domain

  Kikoa maalum kilichothibitishwa, au kikoa cha msingi. Chaguo-msingi ni kikoa cha msingi.

  Hiari
• type

  direct (chaguo-msingi), utm, appstore, instagram, mobile au device. Zote isipokuwa direct na utm zinahitaji mpango wa Solo, Growth au Ultimate.

  Hiari
• utm_source, utm_medium, utm_campaign

  Kwa viungo vya utm; utm_source inahitajika type ikiwa utm.

  Hiari
• ios_url, android_url

  Anwani lengwa za majukwaa kwa viungo vya appstore na mobile.

  Hiari
• desktop_url, mobile_url

  Zote zinahitajika kwa viungo vya device.

  Hiari
• instagram_username

  Kwa viungo vya instagram.

  Hiari
• split_variations

  Safu ya vitu vya {name, url, weight} — angalau viwili — ili kuendesha jaribio la mgawanyo lenye uzito kwenye kiungo cha direct au utm.

  Hiari
• limit_visits_per_device

  Weka true na utoe visit_limit_per_device ili kuweka kikomo cha ziara kwa saa kwa kila kifaa.

  Hiari

curl -X POST https://letl.ink/api/v1/links \
  -H "X-API-KEY: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "destination": "https://shop.example.com/spring",
        "short_code": "spring",
        "title": "Spring sale",
        "type": "utm",
        "utm_source": "twitter",
        "utm_campaign": "spring"
      }'

The created link, in the shape shown above.

Unda viungo vingi kwa ombi moja. Kila safu hujaribiwa kivyake: safu halali huundwa na zilizoshindwa huripotiwa kwa kila faharasa, hivyo URL moja mbovu haitupi kamwe sehemu iliyobaki ya kundi. Hurudisha 201 chochote kikiundwa, 422 pasipo kuundwa chochote.

curl -X POST https://letl.ink/api/v1/links/bulk \
  -H "X-API-KEY: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"links":[
        {"destination":"https://example.com/1","short_code":"one"},
        {"destination":"https://example.com/2"}
      ]}'

{
  "data": [ { "id": 51, "short_code": "one", … } ],
  "meta": {
    "requested": 2,
    "created": 1,
    "failed": 1,
    "errors": [
      { "index": 1,
        "code": "invalid_request",
        "message": "This shortcode is already taken.",
        "short_code": "two" }
    ]
  }
}

PATCH huunganisha: sehemu unazotuma pekee ndizo hubadilishwa, kila kitu kingine hubaki na thamani yake ya sasa. PUT hubadilisha kabisa: chochote unachoacha hufutwa. Inakubali sehemu zilezile kama za kuunda.

curl -X PATCH https://letl.ink/api/v1/links/49 \
  -H "X-API-KEY: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Spring sale — extended"}'

Huweka kiungo kwenye kumbukumbu: kinaacha kufanya kazi na kuachilia nafasi ya kikomo, huku historia yake ya mibofyo ikihifadhiwa. Kwa makusudi hakuna ufutaji wa kudumu kwenye API — kuharibu kiungo na historia yake kunabaki kuwa kitendo cha dashibodi kinachohitaji uthibitisho wa wazi.

Hurudisha kiungo kilicho kwenye kumbukumbu kwenye matumizi. Hurudisha 403 plan_required ikiwa eneo la kazi tayari limefikia kikomo chake cha viungo vinavyotumika.

Ziara moja moja kwenye kiungo kimoja, za karibuni kwanza. Inakubali limit na offset. Nchi imejumuishwa kwenye kila mpango.

Namba kuu za eneo lote la kazi: mibofyo ya muda wote na ndani ya kipindi, wageni wa kipekee, skani za QR, siku ya kilele, na mgawanyo kwa saa ya siku na siku ya wiki. Hupokea days (chaguo-msingi 30, hubanwa kwenye uhifadhi wako).

{
  "data": {
    "window_days": 30,
    "clicks": {
      "total": 24592, "window": 8140, "last_7_days": 2103,
      "daily_average": 271,
      "peak_day": { "date": "Sep 02", "clicks": 612 }
    },
    "visitors": { "unique_total": 18204, "unique_window": 6021 },
    "qr": { "scans_total": 940, "scans_window": 310 },
    "timing": {
      "by_hour": [12, 4, 2, …],
      "by_weekday": [1420, 1610, 1585, 1490, 1310, 480, 245],
      "peak_hour": { "peakHour": 14, "peakValue": 812, "label": "14:00–14:59" },
      "peak_weekday": { "peakDay": 1, "peakValue": 1610, "label": "Tuesday" }
    },
    "links": { "active": 42, "limit": 200 }
  },
  "meta": { "plan": "growth", "geo_included": true, "retention_days": 365 }
}

Idadi ya mibofyo ya kila siku, tayari kwa chati. Tuma link_id ili kuiwekea kiungo kimoja, na days kuweka kipindi. Siku zisizo na trafiki hurudishwa kama sifuri badala ya kuachwa, hivyo mfululizo huwa endelevu kila mara.

{
  "data": [
    { "date": "Sep 04", "clicks": 22 },
    { "date": "Sep 05", "clicks": 11 }
  ],
  "meta": { "window_days": 7, "total": 33, "link_id": null }
}

Mibofyo iliyopangwa kwa kipimo kimoja, pamoja na mgao wa kila safu katika jumla.

Vigezo vya hoja (query)

• dimension string

  channel, referrer, device, browser, os, brand, variation au country. browser, os, brand na variation zinahitaji link_id.

  Inahitajika
• link_id integer

  Weka kikomo kwa kiungo kimoja. Liache kwa eneo lote la kazi.

  Hiari
• limit integer

  1–100. Chaguo-msingi ni 10.

  Hiari

{
  "data": [
    { "label": "Search", "value": 215, "share": 33.1 },
    { "label": "Social", "value": 201, "share": 30.9 },
    { "label": "Direct / none", "value": 142, "share": 21.8 }
  ],
  "meta": { "dimension": "channel", "link_id": 49, "total": 650 }
}

Kila kitu ambacho dashibodi inaonyesha kwa kiungo kimoja katika wito mmoja: kiungo chenyewe, jumla ya mibofyo, wageni wa kipekee na wanaorudi, mfululizo wa kila siku, mgawanyo wa saa na siku za wiki, uchambuzi wote, na ubao wa matokeo wa jaribio la mgawanyo kiungo kikiwa kinaendesha moja.

"split_test": {
  "active": true,
  "conclusive": true,
  "minClicks": 100,
  "leader": "control",
  "totalClicks": 650,
  "totalVisitors": 172,
  "arms": [
    { "name": "control", "isControl": true, "weight": 2,
      "clicks": 357, "visitors": 60,
      "expectedShare": 50.0, "actualShare": 54.9, "drift": 4.9 },
    { "name": "variant-b", "isControl": false, "weight": 1,
      "clicks": 146, "visitors": 57,
      "expectedShare": 25.0, "actualShare": 22.5, "drift": -2.5 }
  ]
}

Mtiririko ghafi wa ziara kwenye kila kiungo katika eneo la kazi, za karibuni kwanza. Hiki ndicho kibadala cha kisasa cha GET /visits: data ile ile, bahasha ya kawaida, na uwezo wa limit na offset.

{
  "data": [
    {
      "id": 2691,
      "link_id": 49,
      "short_code": "spring",
      "occurred_at": "2026-09-10T22:45:33+00:00",
      "ip_address": "203.0.113.7",
      "referrer": "https://twitter.com/",
      "browser": "Chrome",
      "os": "iOS",
      "device_type": "mobile",
      "device_brand": "Apple",
      "country": "US",
      "variation": "control"
    }
  ],
  "meta": { "limit": 50, "returned": 50, "geo_included": true }
}

Endpoint za webhook zilizosajiliwa kwenye akaunti hii.

Sajili endpoint ya HTTPS ili kupokea data ya JSON kwa kila mbofyo uliorekodiwa. Hadi 25 kwa kila akaunti. Uwasilishaji ulioshindwa hujaribiwa upya kiotomatiki.

Mwili wa JSON

• target_url

  Lazima iwe https://.

  Inahitajika
• event

  Chaguo-msingi ni link_visited, ambalo kwa sasa ndilo tukio pekee.

  Hiari

curl -X POST https://letl.ink/api/v1/hooks \
  -H "X-API-KEY: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target_url": "https://example.com/hooks/clicks"}'

Ondoa endpoint ya webhook. POST /hooks/subscribe na DELETE /hooks/unsubscribe/{id} bado vinapatikana kwa mtiririko wa REST Hook wa Zapier.

Jaribio la awali la muunganisho: hurudisha user id yako, barua pepe na id/jina la eneo la kazi kama kitu bapa. GET /me hurudisha utambulisho huo huo pamoja na vikomo vya mpango wako na feature flags, na ndilo chaguo bora kwa msimbo mpya.

curl -H "X-API-KEY: YOUR_TOKEN" \
  https://letl.ink/api/v1/auth/me

{
  "id": 1,
  "email": "[email protected]",
  "workspace_id": 12,
  "workspace_name": "My Workspace"
}

Jumla ya mibofyo kwa kiungo kimoja, kinachotambuliwa kwa domain na slug badala ya kitambulisho. Vigezo vyote viwili vinahitajika. GET /links/{id} na GET /analytics/links/{id} hufanya kazi hiyo hiyo unapojua kitambulisho.

Vigezo vya hoja (query)

• domain string

  Kikoa cha msingi au mojawapo ya vikoa vyako maalum vilivyothibitishwa.

  Inahitajika
• slug string

  Msimbo mfupi, bila mkwaju wa mwanzo.

  Inahitajika
• start_date date

  YYYY-MM-DD, hubanwa kwenye muda wa uhifadhi wa mpango wako.

  Hiari
• end_date date

  YYYY-MM-DD, ikijumuisha.

  Hiari

Ziara 50 za hivi karibuni katika eneo la kazi kama safu tupu ya JSON — bila bahasha — zikitumia majina ya sehemu visit_id, visit_time, link_shortcode na visitor_*. Hiki ndicho hatua ya "perform list" ya REST Hook ya Zapier husoma, kwa hivyo muundo wake umegandishwa. Tumia GET /events kwa kazi mpya.

Ziara 50 za hivi karibuni kwenye kiungo kimoja, kama safu tupu yenye created_at, ip_address, country, device_type, browser, os na referrer. Imegandishwa pamoja na /visits; tumia GET /links/{id}/events kwa kazi mpya.

Usajili wa REST Hook. Hupokea target_url na event ya hiari (chaguo-msingi link_visited) na hurudisha usajili ulioundwa moja kwa moja, bila bahasha. POST /hooks ni operesheni ile ile katika muundo wa kawaida.

Kujiondoa kwenye REST Hook, hurudisha {"success": true}. DELETE /hooks/{id} ndiyo sawa nayo katika muundo wa kawaida.