Anar al contingut
cutty.dev
Per a desenvolupadors

API i servidor MCP

Crea i gestiona enllaços curts des del teu propi codi: amb l'API REST o a través d'un servidor MCP al teu assistent d'IA.

cutty té una API pública i un servidor MCP. La primera et permet crear i modificar enllaços des del codi; el segon funciona directament des d'un assistent d'IA que parla el protocol MCP. Tots dos fan servir la mateixa clau d'API.

Clau d'API

Autentica cada crida amb una capçalera:

Authorization: Bearer ck_your_key

On aconseguir una clau: inicia sessió, obre el teu tauler → Claus d'API → Crea una clau. La clau completa (comença per ck_) només es mostra un cop, en crear-la: desa-la de seguida en un lloc segur. El límit és de 120 sol·licituds per minut i clau.

URL base

Tots els endpoints REST viuen sota https://cutty.dev/api/v1. Les sol·licituds i les respostes són JSON.

Crear un enllaç

POST /api/v1/links — el cos JSON necessita com a mínim una url. La resta és opcional:

  • url — adreça de destinació (obligatòria)
  • slug — final personalitzat, de 3 a 40 caràcters; omet-lo per obtenir-ne un d'aleatori
  • expiresAt — data de caducitat en format ISO 8601
  • maxHits — límit de clics (1–1.000.000)
  • password — contrasenya que protegeix l'enllaç
  • tags — etiquetes separades per comes per organitzar al tauler
  • folder — nom de la carpeta on va l'enllaç
  • utmSource, utmMedium, utmCampaign — paràmetres UTM afegits en la redirecció

La resposta et dóna 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"}'

Llistar i un sol enllaç

GET /api/v1/links retorna tots els teus enllaços. GET /api/v1/links/{slug} — els detalls d'un.

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

Actualitzar i eliminar

PATCH /api/v1/links/{slug} actualitza els camps que hi passes, DELETE /api/v1/links/{slug} elimina l'enllaç.

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

Amb PATCH pots definir, entre d'altres: targetUrl, expiresAt, maxHits, status, password, tags, folder, més els camps avançats de més avall. Un camp posat a null (o una cadena buida) esborra aquesta propietat.

Segmentació, A/B i camps avançats

Les mateixes coses que tens a l'editor d'enllaços estan disponibles per l'API:

  • rules — un array de regles de redirecció per país o dispositiu, p. ex. [{"kind":"country","match":"PL","url":"https://shop.pl"},{"kind":"device","match":"ios","url":"https://apps.apple.com/..."}]
  • abUrls — rotació A/B: un array [{"url":"https://a.com","weight":1},{"url":"https://b.com","weight":1}]; s'usa quan cap regla no encaixa
  • startsAt — data (ISO 8601) en què l'enllaç s'activa; abans, l'enllaç retorna 425
  • webhookUrl — adreça que rep una notificació POST a cada clic (fire-and-forget)
  • serveOg amb ogTitle, ogDescription, ogImageUrl — una targeta de previsualització personalitzada per als crawlers socials (les persones igualment reben la redirecció)
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"}]}'

Operacions en bloc

POST /api/v1/bulk crea molts enllaços en una sola sol·licitud. Passa un array links (cada element com una creació normal), fins a 500 alhora. La resposta retorna un resultat per fila.

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

Estadístiques de l'enllaç

GET /api/v1/links/{slug}/stats retorna un resum de clics: el total, un desglossament per dispositiu i navegador, i la distribució de les últimes 24 hores.

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

Servidor MCP

Si treballes amb un assistent d'IA, pots connectar cutty per MCP (Model Context Protocol) i demanar-li que escurci i organitzi enllaços dins de la conversa. El servidor s'executa a https://mcp.cutty.dev/mcp sobre Streamable HTTP, i t'autentiques amb la mateixa clau d'API: la capçalera Authorization: Bearer ck_....

La llista completa d'eines, els fragments de connexió i els exemples són en una pàgina dedicada: servidor MCP de cutty.

Alguna cosa no funciona?

Escriu a [email protected] — responc el mateix dia.