Átjuks a tartalomhoz
cutty.dev
Fejlesztőknek

API és MCP-szerver

Hozz létre és kezelj rövid linkeket a saját kódodból — a REST API-n keresztül vagy MCP-szerverrel az AI-asszisztensedben.

A cutty rendelkezik nyilvános API-val és egy MCP-szerverrel. Az első lehetővé teszi, hogy kódból hozz létre és módosíts linkeket; a második közvetlenül egy MCP-protokollt beszélő AI-asszisztensből működik. Mindkettő ugyanazt az API-kulcsot használja.

API-kulcs

Minden hívást hitelesíts egy fejléccel:

Authorization: Bearer ck_your_key

Honnan szerezhetsz kulcsot: jelentkezz be, nyisd meg a vezérlőpultodat → API-kulcsok → Kulcs létrehozása. A teljes kulcs (a ck_ előtaggal kezdődik) csak egyszer jelenik meg, létrehozáskor — mentsd el rögtön biztonságos helyre. A korlát percenként 120 kérés kulcsonként.

Alap-URL

Minden REST-végpont a https://cutty.dev/api/v1 alatt található. A kérések és válaszok JSON formátumúak.

Link létrehozása

POST /api/v1/links — a JSON-törzsnek legalább egy url mezőre van szüksége. A többi opcionális:

  • url — célcím (kötelező)
  • slug — egyéni végződés, 3–40 karakter; hagyd el véletlenszerűhöz
  • expiresAt — lejárati dátum ISO 8601 formátumban
  • maxHits — kattintási korlát (1–1 000 000)
  • password — a linket védő jelszó
  • tags — vesszővel elválasztott címkék a vezérlőpulti rendszerezéshez
  • folder — annak a mappának a neve, amelybe a link kerül
  • utmSource, utmMedium, utmCampaign — átirányításkor hozzáfűzött UTM-paraméterek

A válasz visszaadja a slug, shortUrl és target mezőket.

curl -X POST https://cutty.dev/api/v1/links \
  -H "Authorization: Bearer ck_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/a/very/long/address","slug":"offer","tags":"campaign,summer"}'

Listázás és egyetlen link

A GET /api/v1/links az összes linkedet adja vissza. A GET /api/v1/links/{slug} — egy adott link részleteit.

curl https://cutty.dev/api/v1/links/offer \
  -H "Authorization: Bearer ck_your_key"

Frissítés és törlés

A PATCH /api/v1/links/{slug} frissíti az átadott mezőket, a DELETE /api/v1/links/{slug} törli a linket.

curl -X PATCH https://cutty.dev/api/v1/links/offer \
  -H "Authorization: Bearer ck_your_key" \
  -H "Content-Type: application/json" \
  -d '{"maxHits":500}'

A PATCH segítségével többek között beállíthatod: targetUrl, expiresAt, maxHits, status, password, tags, folder, valamint az alábbi haladó mezőket. Egy null értékre (vagy üres karakterláncra) állított mező törli az adott tulajdonságot.

Targetálás, A/B és haladó mezők

Ugyanaz, amit a linkszerkesztőben kapsz, elérhető az API-n keresztül is:

  • rules — átirányítási szabályok tömbje ország vagy eszköz szerint, pl. [{"kind":"country","match":"PL","url":"https://shop.pl"},{"kind":"device","match":"ios","url":"https://apps.apple.com/..."}]
  • abUrls — A/B-rotáció: egy tömb [{"url":"https://a.com","weight":1},{"url":"https://b.com","weight":1}]; akkor használatos, ha egyik szabály sem illik
  • startsAt — a dátum (ISO 8601), amikor a link élesedik; ez előtt a link 425-öt ad vissza
  • webhookUrl — cím, amely minden kattintáskor POST értesítést kap (fire-and-forget)
  • serveOg az ogTitle, ogDescription, ogImageUrl mezőkkel — saját előnézeti kártya a közösségi botoknak (az emberek továbbra is az átirányítást kapják)
curl -X PATCH https://cutty.dev/api/v1/links/offer \
  -H "Authorization: Bearer ck_your_key" \
  -H "Content-Type: application/json" \
  -d '{"rules":[{"kind":"country","match":"DE","url":"https://example.de"}]}'

Tömeges műveletek

A POST /api/v1/bulk sok linket hoz létre egyetlen kérésben. Adj át egy links tömböt (minden elem olyan, mint egy sima létrehozás), egyszerre legfeljebb 500-at. A válasz soronként ad vissza eredményt.

curl -X POST https://cutty.dev/api/v1/bulk \
  -H "Authorization: Bearer ck_your_key" \
  -H "Content-Type: application/json" \
  -d '{"links":[{"url":"https://a.com"},{"url":"https://b.com","slug":"b"}]}'

Link-statisztika

A GET /api/v1/links/{slug}/stats kattintási összegzést ad vissza: az összeset, eszköz és böngésző szerinti bontást, valamint az elmúlt 24 óra eloszlását.

curl https://cutty.dev/api/v1/links/offer/stats \
  -H "Authorization: Bearer ck_your_key"

MCP-szerver

Ha AI-asszisztenssel dolgozol, a cuttyt MCP-n (Model Context Protocol) keresztül csatlakoztathatod, és megkérheted, hogy egyenesen a beszélgetésben rövidítsen és rendszerezzen linkeket. A szerver a https://mcp.cutty.dev/mcp címen fut Streamable HTTP-n, és ugyanazzal az API-kulccsal hitelesítesz — az Authorization: Bearer ck_... fejléccel.

A teljes eszközlista, a kész csatlakozási kódrészletek és a példák külön oldalon találhatók: cutty MCP-kiszolgáló.

Valami nem működik?

Írj a [email protected] címre — még aznap válaszolok.