Siirry sisältöön
cutty.dev
Kehittäjille

API ja MCP-palvelin

Luo ja hallitse lyhytlinkkejä omasta koodistasi — REST-API:n kautta tai MCP-palvelimella AI-avustajassasi.

cutty tarjoaa julkisen API:n ja MCP-palvelimen. Ensimmäisellä luot ja muutat linkkejä koodista; toinen toimii suoraan tekoälyavustajasta, joka puhuu MCP-protokollaa. Molemmat käyttävät samaa API-avainta.

API-avain

Tunnistaudu jokaisessa kutsussa otsakkeella:

Authorization: Bearer ck_your_key

Mistä saat avaimen: kirjaudu sisään, avaa hallintapaneeli → API-avaimet → Luo avain. Koko avain (se alkaa merkeillä ck_) näytetään vain kerran, luonnin yhteydessä — tallenna se heti turvalliseen paikkaan. Raja on 120 pyyntöä minuutissa avainta kohden.

Perus-URL

Kaikki REST-päätepisteet sijaitsevat osoitteessa https://cutty.dev/api/v1. Pyynnöt ja vastaukset ovat JSON-muodossa.

Linkin luominen

POST /api/v1/links — JSON-rungossa tarvitaan vähintään url. Loput ovat valinnaisia:

  • url — kohdeosoite (pakollinen)
  • slug — oma pääte, 3–40 merkkiä; jätä pois saadaksesi satunnaisen
  • expiresAt — vanhenemispäivä ISO 8601 -muodossa
  • maxHits — klikkausraja (1–1 000 000)
  • password — linkin suojaava salasana
  • tags — pilkulla erotellut tunnisteet järjestelyä varten hallintapaneelissa
  • folder — kansion nimi, johon linkki menee
  • utmSource, utmMedium, utmCampaign — UTM-parametrit, jotka lisätään uudelleenohjauksessa

Vastaus antaa sinulle slug, shortUrl ja target.

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"}'

Listaus ja yksittäinen linkki

GET /api/v1/links palauttaa kaikki linkkisi. GET /api/v1/links/{slug} — yhden linkin tiedot.

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

Päivittäminen ja poistaminen

PATCH /api/v1/links/{slug} päivittää antamasi kentät, DELETE /api/v1/links/{slug} poistaa linkin.

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

Komennolla PATCH voit asettaa muun muassa: targetUrl, expiresAt, maxHits, status, password, tags, folder sekä alla olevat lisäkentät. Arvoon null (tai tyhjään merkkijonoon) asetettu kenttä tyhjentää kyseisen ominaisuuden.

Kohdistus, A/B ja lisäkentät

Samat asiat, jotka saat linkkieditorissa, ovat käytettävissä API:n kautta:

  • rules — taulukko uudelleenohjaussäännöistä maan tai laitteen mukaan, esim. [{"kind":"country","match":"PL","url":"https://shop.pl"},{"kind":"device","match":"ios","url":"https://apps.apple.com/..."}]
  • abUrls — A/B-kierto: taulukko [{"url":"https://a.com","weight":1},{"url":"https://b.com","weight":1}]; käytetään, kun mikään sääntö ei täsmää
  • startsAt — päivä (ISO 8601), jolloin linkki tulee voimaan; sitä ennen linkki palauttaa 425
  • webhookUrl — osoite, joka saa POST-ilmoituksen jokaisesta klikkauksesta (fire-and-forget)
  • serveOg yhdessä kenttien ogTitle, ogDescription, ogImageUrl kanssa — oma esikatselukortti sosiaalisen median roboteille (ihmiset saavat silti uudelleenohjauksen)
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"}]}'

Joukko-operaatiot

POST /api/v1/bulk luo monta linkkiä yhdellä pyynnöllä. Anna links-taulukko (jokainen alkio kuten tavallisessa luonnissa), enintään 500 kerrallaan. Vastaus palauttaa tuloksen riviä kohden.

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"}]}'

Linkin tilastot

GET /api/v1/links/{slug}/stats palauttaa yhteenvedon klikkauksista: kokonaismäärän, erittelyn laitteen ja selaimen mukaan sekä jakauman viimeisten 24 tunnin ajalta.

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

MCP-palvelin

Jos työskentelet tekoälyavustajan kanssa, voit yhdistää cuttyn MCP:n (Model Context Protocol) kautta ja pyytää sitä lyhentämään ja järjestämään linkkejä suoraan keskustelussa. Palvelin toimii osoitteessa https://mcp.cutty.dev/mcp Streamable HTTP:n yli, ja tunnistaudut samalla API-avaimella — otsakkeella Authorization: Bearer ck_....

Täydellinen työkalulista, valmiit yhteysesimerkit ja esimerkit ovat omalla sivullaan: cuttyn MCP-palvelin.

Jokin ei toimi?

Kirjoita osoitteeseen [email protected] — vastaan samana päivänä.