Vai al contenuto
cutty.dev
Per sviluppatori

API e server MCP

Crea e gestisci link brevi dal tuo codice — tramite l'API REST o un server MCP nel tuo assistente AI.

cutty ha una API pubblica e un server MCP. La prima ti permette di creare e modificare link da codice; il secondo funziona direttamente da un assistente AI che parla il protocollo MCP. Entrambi usano la stessa API key.

API key

Autentica ogni chiamata con un header:

Authorization: Bearer ck_your_key

Dove ottenere una chiave: accedi, apri la tua dashboard → API keys → Crea chiave. La chiave completa (inizia con ck_) viene mostrata una sola volta, alla creazione — salvala subito in un posto sicuro. Il limite è di 120 richieste al minuto per chiave.

Base URL

Tutti gli endpoint REST si trovano sotto https://cutty.dev/api/v1. Richieste e risposte sono in JSON.

Creare un link

POST /api/v1/links — il corpo JSON richiede almeno un url. Il resto è opzionale:

  • url — indirizzo di destinazione (obbligatorio)
  • slug — finale personalizzato, 3–40 caratteri; ometti per uno casuale
  • expiresAt — data di scadenza in formato ISO 8601
  • maxHits — limite di clic (1–1.000.000)
  • password — password che protegge il link
  • tags — etichette separate da virgola per organizzare nella dashboard
  • folder — nome della cartella in cui finisce il link
  • utmSource, utmMedium, utmCampaign — parametri UTM aggiunti al reindirizzamento

La risposta ti restituisce slug, shortUrl e 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"}'

Elenco e singolo link

GET /api/v1/links restituisce tutti i tuoi link. GET /api/v1/links/{slug} — i dettagli di uno.

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

Aggiornare ed eliminare

PATCH /api/v1/links/{slug} aggiorna i campi che passi, DELETE /api/v1/links/{slug} rimuove il link.

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

Tramite PATCH puoi impostare, tra gli altri: targetUrl, expiresAt, maxHits, status, password, tags, folder, oltre ai campi avanzati qui sotto. Un campo impostato a null (o a una stringa vuota) cancella quella proprietà.

Targeting, A/B e campi avanzati

Le stesse cose che trovi nell'editor del link sono disponibili tramite la API:

  • rules — un array di regole di reindirizzamento per paese o dispositivo, es. [{"kind":"country","match":"PL","url":"https://shop.pl"},{"kind":"device","match":"ios","url":"https://apps.apple.com/..."}]
  • abUrls — rotazione A/B: un array [{"url":"https://a.com","weight":1},{"url":"https://b.com","weight":1}]; usato quando nessuna regola corrisponde
  • startsAt — data (ISO 8601) in cui il link entra in funzione; prima di allora il link restituisce 425
  • webhookUrl — indirizzo che riceve una notifica POST a ogni clic (fire-and-forget)
  • serveOg con ogTitle, ogDescription, ogImageUrl — una scheda di anteprima personalizzata per i crawler social (le persone ricevono comunque il reindirizzamento)
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"}]}'

Operazioni in blocco

POST /api/v1/bulk crea molti link in un'unica richiesta. Passa un array links (ogni elemento come una normale creazione), fino a 500 alla volta. La risposta restituisce un risultato per ogni riga.

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

Statistiche del link

GET /api/v1/links/{slug}/stats restituisce un riepilogo dei clic: il totale, la suddivisione per dispositivo e browser e la distribuzione nelle ultime 24 ore.

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

Server MCP

Se lavori con un assistente AI, puoi collegare cutty tramite MCP (Model Context Protocol) e chiedergli di accorciare e organizzare i link direttamente nella conversazione. Il server gira su https://mcp.cutty.dev/mcp via Streamable HTTP e ti autentichi con la stessa API key — l'header Authorization: Bearer ck_....

L'elenco completo degli strumenti, gli snippet di connessione pronti all'uso e gli esempi sono in una pagina dedicata: server MCP di cutty.

Qualcosa non funziona?

Scrivi a [email protected] — rispondo in giornata.