Přejít na obsah
cutty.dev
Pro vývojáře

API a MCP server

Vytvářejte a spravujte krátké odkazy přímo z vlastního kódu — přes REST API nebo přes MCP server ve vašem AI asistentovi.

cutty má veřejné API a MCP server. První umožňuje vytvářet a měnit odkazy z kódu; druhý funguje přímo z AI asistenta, který mluví protokolem MCP. Oba používají stejný API klíč.

API klíč

Každé volání ověřte hlavičkou:

Authorization: Bearer ck_your_key

Kde získat klíč: přihlaste se, otevřete nástěnku → API klíče → Vytvořit klíč. Celý klíč (začíná na ck_) se zobrazí jen jednou, při vytvoření — hned si ho někam bezpečně uložte. Limit je 120 požadavků za minutu na klíč.

Základní URL

Všechny REST endpointy jsou pod https://cutty.dev/api/v1. Požadavky i odpovědi jsou ve formátu JSON.

Vytvoření odkazu

POST /api/v1/links — tělo JSON potřebuje alespoň url. Zbytek je volitelný:

  • url — cílová adresa (povinné)
  • slug — vlastní koncovka, 3–40 znaků; vynechte pro náhodnou
  • expiresAt — datum vypršení ve formátu ISO 8601
  • maxHits — limit kliknutí (1–1 000 000)
  • password — heslo chránící odkaz
  • tags — štítky oddělené čárkou pro uspořádání v nástěnce
  • folder — název složky, do které odkaz patří
  • utmSource, utmMedium, utmCampaign — UTM parametry připojené při přesměrování

Odpověď vám vrátí slug, shortUrl a 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"}'

Výpis a jeden odkaz

GET /api/v1/links vrátí všechny vaše odkazy. GET /api/v1/links/{slug} — detail jednoho.

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

Úprava a mazání

PATCH /api/v1/links/{slug} aktualizuje pole, která pošlete, DELETE /api/v1/links/{slug} odkaz odstraní.

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

Přes PATCH můžete nastavit mimo jiné: targetUrl, expiresAt, maxHits, status, password, tags, folder a pokročilá pole níže. Pole nastavené na null (nebo prázdný řetězec) danou vlastnost vymaže.

Cílení, A/B a pokročilá pole

To samé, co máte v editoru odkazu, je dostupné i přes API:

  • rules — pole pravidel přesměrování podle země nebo zařízení, např. [{"kind":"country","match":"PL","url":"https://shop.pl"},{"kind":"device","match":"ios","url":"https://apps.apple.com/..."}]
  • abUrls — A/B rotace: pole [{"url":"https://a.com","weight":1},{"url":"https://b.com","weight":1}]; použije se, když nesedí žádné pravidlo
  • startsAt — datum (ISO 8601), kdy se odkaz spustí; předtím odkaz vrací 425
  • webhookUrl — adresa, která dostane oznámení POST při každém kliknutí (fire-and-forget)
  • serveOg s ogTitle, ogDescription, ogImageUrl — vlastní náhledová karta pro roboty sociálních sítí (lidé dostanou přesměrování dál)
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"}]}'

Hromadné operace

POST /api/v1/bulk vytvoří mnoho odkazů v jednom požadavku. Pošlete pole links (každá položka jako běžné vytvoření), až 500 najednou. Odpověď vrátí výsledek pro každý řádek.

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

Statistiky odkazu

GET /api/v1/links/{slug}/stats vrátí souhrn kliknutí: celkový počet, rozpad podle zařízení a prohlížeče a rozložení za posledních 24 hodin.

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

MCP server

Pokud pracujete s AI asistentem, můžete cutty připojit přes MCP (Model Context Protocol) a požádat ho, aby zkracoval a uspořádával odkazy přímo v konverzaci. Server běží na https://mcp.cutty.dev/mcp přes Streamable HTTP a ověřujete se stejným API klíčem — hlavičkou Authorization: Bearer ck_....

Úplný seznam nástrojů, ukázky připojení a příklady najdeš na samostatné stránce: MCP server cutty.

Něco nefunguje?

Napište na [email protected] — odpovídám týž den.