Przejdź do treści
cutty.dev
Dla deweloperów

API i serwer MCP

Twórz i zarządzaj krótkimi linkami z poziomu kodu — przez REST API albo przez serwer MCP w Twoim asystencie AI.

cutty ma publiczne API i serwer MCP. Pierwsze pozwala tworzyć i zmieniać linki z poziomu kodu, drugie — wprost z asystenta AI, który mówi protokołem MCP. Oba używają tego samego klucza API.

Klucz API

Każde wywołanie uwierzytelniasz nagłówkiem:

Authorization: Bearer ck_twój_klucz

Skąd wziąć klucz: zaloguj się, wejdź w panel → Klucze API → Utwórz klucz. Pełny klucz (zaczyna się od ck_) pokazujemy tylko raz, przy tworzeniu — zapisz go od razu w bezpiecznym miejscu. Limit to 120 żądań na minutę na klucz.

Bazowy adres

Wszystkie endpointy REST żyją pod https://cutty.dev/api/v1. Żądania i odpowiedzi są w formacie JSON.

Tworzenie linku

POST /api/v1/links — w ciele JSON podajesz co najmniej url. Reszta jest opcjonalna:

  • url — adres docelowy (wymagane)
  • slug — własna końcówka, 3–40 znaków; pominięta = losowa
  • expiresAt — data wygaśnięcia w formacie ISO 8601
  • maxHits — limit kliknięć (1–1 000 000)
  • password — hasło chroniące link
  • tags — etykiety po przecinku, do porządkowania w panelu
  • folder — nazwa folderu, do którego trafia link
  • utmSource, utmMedium, utmCampaign — parametry UTM doklejane przy przekierowaniu

W odpowiedzi dostajesz slug, shortUrl i target.

curl -X POST https://cutty.dev/api/v1/links \
  -H "Authorization: Bearer ck_twój_klucz" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://przyklad.pl/bardzo/dlugi/adres","slug":"oferta","tags":"kampania,lato"}'

Lista i pojedynczy link

GET /api/v1/links zwraca wszystkie Twoje linki. GET /api/v1/links/{slug} — szczegóły jednego.

curl https://cutty.dev/api/v1/links/oferta \
  -H "Authorization: Bearer ck_twój_klucz"

Zmiana i usunięcie

PATCH /api/v1/links/{slug} aktualizuje wybrane pola, DELETE /api/v1/links/{slug} usuwa link.

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

Przez PATCH ustawisz między innymi: targetUrl, expiresAt, maxHits, status, password, tags, folder, a także pola zaawansowane opisane niżej. Pole z wartością null (albo pustym tekstem) czyści daną właściwość.

Targetowanie, A/B i pola zaawansowane

Te same możliwości, które masz w edytorze linku, ustawisz też przez API:

  • rules — tablica reguł przekierowań wg kraju lub urządzenia, np. [{"kind":"country","match":"PL","url":"https://sklep.pl"},{"kind":"device","match":"ios","url":"https://apps.apple.com/..."}]
  • abUrls — rotacja A/B: tablica [{"url":"https://a.pl","weight":1},{"url":"https://b.pl","weight":1}]; używana, gdy żadna reguła nie pasuje
  • startsAt — data (ISO 8601), od której link zaczyna działać; wcześniej zwraca 425
  • webhookUrl — adres, pod który przy każdym kliknięciu leci powiadomienie POST (fire-and-forget)
  • serveOg oraz ogTitle, ogDescription, ogImageUrl — własna karta podglądu dla botów social mediów (człowiek i tak dostaje przekierowanie)
curl -X PATCH https://cutty.dev/api/v1/links/oferta \
  -H "Authorization: Bearer ck_twój_klucz" \
  -H "Content-Type: application/json" \
  -d '{"rules":[{"kind":"country","match":"DE","url":"https://przyklad.de"}]}'

Operacje zbiorcze

POST /api/v1/bulk zakłada wiele linków jednym żądaniem. W ciele podajesz tablicę links (każdy element jak przy zwykłym tworzeniu), maksymalnie 500 naraz. W odpowiedzi dostajesz wynik dla każdego wiersza.

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

Statystyki linku

GET /api/v1/links/{slug}/stats zwraca podsumowanie kliknięć: łączną liczbę, podział na urządzenia i przeglądarki oraz rozkład na ostatnią dobę.

curl https://cutty.dev/api/v1/links/oferta/stats \
  -H "Authorization: Bearer ck_twój_klucz"

Serwer MCP

Pracujesz z asystentem AI? cutty ma też serwer MCP — podłączasz go raz i zarządzasz linkami wprost w rozmowie. Działa pod https://mcp.cutty.dev/mcp (transport Streamable HTTP), a uwierzytelniasz się tym samym kluczem ck_ co w API.

Pełna lista dziesięciu narzędzi (w tym targetowanie po kraju/urządzeniu i testy A/B), gotowe snippety podłączenia dla Claude Code, Cursora i Claude Desktop oraz przykłady — na osobnej stronie: serwer MCP cutty.

Coś nie działa?

Napisz na [email protected] — odpisuję tego samego dnia.