Mergi la conținut
cutty.dev
Pentru dezvoltatori

API și server MCP

Creează și gestionează linkuri scurte direct din codul tău — prin API-ul REST sau printr-un server MCP în asistentul tău AI.

cutty are un API public și un server MCP. Primul îți permite să creezi și să modifici linkuri din cod; al doilea funcționează direct dintr-un asistent AI care vorbește protocolul MCP. Ambele folosesc aceeași cheie API.

Cheie API

Autentifică fiecare apel cu un header:

Authorization: Bearer ck_your_key

De unde iei o cheie: autentifică-te, deschide panoul → API keys → Create key. Cheia completă (începe cu ck_) se afișează o singură dată, la creare — salveaz-o imediat într-un loc sigur. Limita este de 120 de cereri pe minut per cheie.

URL de bază

Toate endpoint-urile REST se află sub https://cutty.dev/api/v1. Cererile și răspunsurile sunt în format JSON.

Crearea unui link

POST /api/v1/links — corpul JSON are nevoie de cel puțin un url. Restul este opțional:

  • url — adresa de destinație (obligatoriu)
  • slug — terminația personalizată, 3–40 de caractere; omite-o pentru una aleatorie
  • expiresAt — data de expirare în format ISO 8601
  • maxHits — limita de clicuri (1–1.000.000)
  • password — parola care protejează linkul
  • tags — etichete separate prin virgulă pentru organizare în panou
  • folder — numele folderului în care intră linkul
  • utmSource, utmMedium, utmCampaign — parametri UTM adăugați la redirecționare

Răspunsul îți oferă slug, shortUrl și 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"}'

Listarea și un singur link

GET /api/v1/links returnează toate linkurile tale. GET /api/v1/links/{slug} — detaliile unuia.

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

Actualizare și ștergere

PATCH /api/v1/links/{slug} actualizează câmpurile pe care le transmiți, DELETE /api/v1/links/{slug} șterge linkul.

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

Prin PATCH poți seta, printre altele: targetUrl, expiresAt, maxHits, status, password, tags, folder, plus câmpurile avansate de mai jos. Un câmp setat la null (sau un șir gol) golește proprietatea respectivă.

Targetare, A/B și câmpuri avansate

Aceleași lucruri pe care le ai în editorul de linkuri sunt disponibile și prin API:

  • rules — un array de reguli de redirecționare după țară sau dispozitiv, de ex. [{"kind":"country","match":"PL","url":"https://shop.pl"},{"kind":"device","match":"ios","url":"https://apps.apple.com/..."}]
  • abUrls — rotație A/B: un array [{"url":"https://a.com","weight":1},{"url":"https://b.com","weight":1}]; folosit când nicio regulă nu se potrivește
  • startsAt — data (ISO 8601) la care linkul devine activ; înainte de ea, linkul returnează 425
  • webhookUrl — adresa care primește o notificare POST la fiecare click (fire-and-forget)
  • serveOg cu ogTitle, ogDescription, ogImageUrl — un card de previzualizare personalizat pentru crawlerele rețelelor sociale (oamenii primesc tot redirecționarea)
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"}]}'

Operații în masă

POST /api/v1/bulk creează multe linkuri într-o singură cerere. Transmite un array links (fiecare element ca la o creare obișnuită), până la 500 odată. Răspunsul returnează câte un rezultat per rând.

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

Statistici pe link

GET /api/v1/links/{slug}/stats returnează un rezumat al clicurilor: totalul, o defalcare pe dispozitiv și browser, și distribuția pe ultimele 24 de ore.

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

Server MCP

Dacă lucrezi cu un asistent AI, poți conecta cutty prin MCP (Model Context Protocol) și să-i ceri să scurteze și să organizeze linkuri chiar în conversație. Serverul rulează la https://mcp.cutty.dev/mcp peste Streamable HTTP, iar autentificarea se face cu aceeași cheie API — headerul Authorization: Bearer ck_....

Lista completă de instrumente, fragmentele de conectare gata de folosit și exemplele se află pe o pagină dedicată: serverul MCP cutty.

Ceva nu funcționează?

Scrie la [email protected] — răspund în aceeași zi.