Ir al contenido
cutty.dev
Para desarrolladores

API y servidor MCP

Crea y gestiona enlaces cortos desde tu propio código, mediante la API REST o a través de un servidor MCP en tu asistente de IA.

cutty tiene una API pública y un servidor MCP. La primera te permite crear y modificar enlaces desde el código; el segundo funciona directamente desde un asistente de IA que habla el protocolo MCP. Ambos usan la misma clave de API.

Clave de API

Autentica cada llamada con una cabecera:

Authorization: Bearer ck_your_key

Dónde conseguir una clave: inicia sesión, abre tu panel → Claves de API → Crear clave. La clave completa (empieza por ck_) se muestra una sola vez, al crearla: guárdala en un lugar seguro de inmediato. El límite es de 120 peticiones por minuto y por clave.

URL base

Todos los endpoints REST están bajo https://cutty.dev/api/v1. Las peticiones y respuestas son JSON.

Crear un enlace

POST /api/v1/links: el cuerpo JSON necesita al menos una url. El resto es opcional:

  • url: dirección de destino (obligatorio)
  • slug: terminación personalizada, de 3 a 40 caracteres; omítelo para uno aleatorio
  • expiresAt: fecha de caducidad en formato ISO 8601
  • maxHits: límite de clics (1–1.000.000)
  • password: contraseña que protege el enlace
  • tags: etiquetas separadas por comas para organizar en el panel
  • folder: nombre de la carpeta donde va el enlace
  • utmSource, utmMedium, utmCampaign: parámetros UTM añadidos en la redirección

La respuesta te devuelve slug, shortUrl y 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"}'

Listar y un enlace concreto

GET /api/v1/links devuelve todos tus enlaces. GET /api/v1/links/{slug}: los detalles de uno.

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

Actualizar y eliminar

PATCH /api/v1/links/{slug} actualiza los campos que envíes, DELETE /api/v1/links/{slug} elimina el enlace.

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

Mediante PATCH puedes establecer, entre otros: targetUrl, expiresAt, maxHits, status, password, tags, folder, además de los campos avanzados de más abajo. Un campo con valor null (o una cadena vacía) borra esa propiedad.

Segmentación, A/B y campos avanzados

Lo mismo que tienes en el editor de enlaces está disponible a través de la API:

  • rules: un array de reglas de redirección por país o dispositivo, p. ej. [{"kind":"country","match":"PL","url":"https://shop.pl"},{"kind":"device","match":"ios","url":"https://apps.apple.com/..."}]
  • abUrls: rotación A/B: un array [{"url":"https://a.com","weight":1},{"url":"https://b.com","weight":1}]; se usa cuando ninguna regla coincide
  • startsAt: fecha (ISO 8601) en la que el enlace se activa; antes de ella, el enlace devuelve 425
  • webhookUrl: dirección que recibe una notificación POST en cada clic (fire-and-forget)
  • serveOg con ogTitle, ogDescription, ogImageUrl: una tarjeta de previsualización personalizada para los rastreadores sociales (las personas siguen yendo a la redirección)
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"}]}'

Operaciones por lotes

POST /api/v1/bulk crea muchos enlaces en una sola petición. Envía un array links (cada elemento como en una creación normal), hasta 500 a la vez. La respuesta devuelve un resultado por 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ísticas del enlace

GET /api/v1/links/{slug}/stats devuelve un resumen de clics: el total, un desglose por dispositivo y navegador, y la distribución de las últimas 24 horas.

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

Servidor MCP

Si trabajas con un asistente de IA, puedes conectar cutty por MCP (Model Context Protocol) y pedirle que acorte y organice enlaces dentro de la propia conversación. El servidor está en https://mcp.cutty.dev/mcp sobre Streamable HTTP, y te autenticas con la misma clave de API: la cabecera Authorization: Bearer ck_....

La lista completa de herramientas, los fragmentos de conexión listos para usar y los ejemplos están en una página dedicada: servidor MCP de cutty.

¿Algo no funciona?

Escribe a [email protected]: respondo el mismo día.