Ir para o conteúdo
cutty.dev
Para programadores

API e servidor MCP

Crie e gira links curtos a partir do seu próprio código — pela API REST ou através de um servidor MCP no seu assistente de IA.

O cutty tem uma API pública e um servidor MCP. A primeira permite criar e alterar links a partir do código; o segundo funciona direto a partir de um assistente de IA que fala o protocolo MCP. Ambos usam a mesma chave de API.

Chave de API

Autentique cada chamada com um cabeçalho:

Authorization: Bearer ck_your_key

Onde obter uma chave: inicie sessão, abra o seu painel → Chaves de API → Criar chave. A chave completa (começa por ck_) é mostrada apenas uma vez, na criação — guarde-a num lugar seguro de imediato. O limite é de 120 pedidos por minuto por chave.

URL base

Todos os endpoints REST ficam em https://cutty.dev/api/v1. Os pedidos e as respostas são em JSON.

Criar um link

POST /api/v1/links — o corpo JSON precisa, no mínimo, de um url. O resto é opcional:

  • url — endereço de destino (obrigatório)
  • slug — terminação personalizada, 3–40 caracteres; omita para uma aleatória
  • expiresAt — data de validade no formato ISO 8601
  • maxHits — limite de cliques (1–1.000.000)
  • password — palavra-passe que protege o link
  • tags — etiquetas separadas por vírgula para organizar no painel
  • folder — nome da pasta para onde vai o link
  • utmSource, utmMedium, utmCampaign — parâmetros UTM acrescentados no redirecionamento

A resposta devolve-lhe 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"}'

Listagem e um único link

GET /api/v1/links devolve todos os seus links. GET /api/v1/links/{slug} — os detalhes de um.

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

Atualizar e apagar

PATCH /api/v1/links/{slug} atualiza os campos que enviar, DELETE /api/v1/links/{slug} remove o 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}'

Através de PATCH pode definir, entre outros: targetUrl, expiresAt, maxHits, status, password, tags, folder, além dos campos avançados abaixo. Um campo definido como null (ou uma string vazia) limpa essa propriedade.

Targeting, A/B e campos avançados

As mesmas coisas que tem no editor de links estão disponíveis pela API:

  • rules — um array de regras de redirecionamento por país ou dispositivo, p. ex. [{"kind":"country","match":"PL","url":"https://shop.pl"},{"kind":"device","match":"ios","url":"https://apps.apple.com/..."}]
  • abUrls — rotação A/B: um array [{"url":"https://a.com","weight":1},{"url":"https://b.com","weight":1}]; usado quando nenhuma regra se aplica
  • startsAt — data (ISO 8601) em que o link entra em funcionamento; antes disso, o link devolve 425
  • webhookUrl — endereço que recebe uma notificação POST a cada clique (fire-and-forget)
  • serveOg com ogTitle, ogDescription, ogImageUrl — um cartão de pré-visualização personalizado para os crawlers de redes sociais (as pessoas continuam a ser redirecionadas)
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ções em lote

POST /api/v1/bulk cria muitos links num único pedido. Envie um array links (cada item como uma criação normal), até 500 de cada vez. A resposta devolve um resultado por linha.

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

Estatísticas do link

GET /api/v1/links/{slug}/stats devolve um resumo de cliques: o total, uma divisão por dispositivo e navegador, e a distribuição ao longo das últimas 24 horas.

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

Servidor MCP

Se trabalha com um assistente de IA, pode ligar o cutty por MCP (Model Context Protocol) e pedir-lhe que encurte e organize links na própria conversa. O servidor corre em https://mcp.cutty.dev/mcp sobre Streamable HTTP, e a autenticação é com a mesma chave de API — o cabeçalho Authorization: Bearer ck_....

A lista completa de ferramentas, os trechos de conexão prontos e exemplos estão numa página dedicada: servidor MCP do cutty.

Algo não funciona?

Escreva para [email protected] — respondo no próprio dia.