Criar link curto

POSThttps://api.curtei.com/v1/links

POST /v1/links no curtei: parâmetros, exemplos em cURL, JavaScript, PHP e Python, resposta e erros. Também listar, editar e apagar links. Escopo: links:write.

Abrir no ChatGPT Abrir no Claude

Cria um link curto para uma URL. Só url é obrigatório. A conta precisa ter o e-mail confirmado.

Parâmetros do corpo

Campo	Tipo	Descrição
`url` (obrigatório)	string	Destino http ou https. Passa pela checagem de segurança (Google Web Risk e lista de bloqueio).
`domain`	string	Domínio do link. Padrão: o domínio padrão da conta (`l.curtei.com`, se você não tiver um próprio).
`slug`	string	Código personalizado (`promo-natal`). Só em domínio próprio; no compartilhado o código é sempre aleatório.
`title`	string	Nome para achar o link no painel.
`redirect_type`	301 ou 302	Tipo do redirecionamento. Padrão: 302.
`expires_at`	ISO-8601	Depois disso o link para de redirecionar.
`max_clicks`	inteiro	Limite de cliques; ao atingir, o link expira.
`password`	string	8 a 128 caracteres. O visitante digita a senha antes de seguir; a resposta traz `has_password`.
`utm`	objeto	`source`, `medium`, `campaign`, `term`, `content`, anexados ao destino.
`tags`	string[]	Etiquetas para filtrar e somar métricas.
`campaign_id`	uuid	Vincula o link a uma campanha.
`external_id`	string	Seu identificador (pedido, cliente). Buscável por `GET /links/by-external-id/{external_id}`.
`metadata`	objeto	Dados livres seus, até 4 KB; voltam nas respostas e nos webhooks.
`track_clicks`	boolean	Registrar cliques. Padrão: `true`.
`track_conversions`	boolean	Requer `track_clicks`. Anexa `wsc_id` ao destino para registrar conversões.
`open_in_app`	boolean	No celular, tenta abrir o app (YouTube, Instagram, WhatsApp, TikTok…) em vez do navegador.
`hide_referrer`	boolean	O destino não fica sabendo de qual página veio o clique.
`rules` / `variants`	objeto[]	Roteamento e teste A/B.

Exemplo

curl -X POST https://api.curtei.com/v1/links \
  -H "Authorization: Bearer $CURTEI_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"url":"https://minhaloja.com.br/promo","tags":["newsletter"]}'

Resposta 201

{
  "id": "0193a0b2-7c1e-7d3a-9f10-5b2c8e4a1d22",
  "short_url": "https://l.curtei.com/aB3xK9",
  "slug": "aB3xK9",
  "domain": "l.curtei.com",
  "url": "https://minhaloja.com.br/promo",
  "status": "active",
  "has_password": false,
  "qr_code_url": "https://api.curtei.com/v1/links/0193a0b2-7c1e-7d3a-9f10-5b2c8e4a1d22/qr",
  "total_clicks": 0,
  "unique_clicks": 0,
  "external_id": null,
  "metadata": null,
  "created_at": "2026-11-13T21:30:00Z"
}

Erros comuns

HTTP	code	O que fazer
400	`invalid_url`	Envie uma URL completa, com `https://`.
403	`email_not_verified`	Confirme o e-mail da conta.
409	`slug_taken`	Escolha outro `slug` ou omita para gerar um aleatório.
422	`url_blocked`	O destino foi classificado como inseguro; `details.reason` diz o motivo.
422	`custom_slug_requires_own_domain`	Cadastre um domínio próprio ou não envie `slug`.
429	`creation_rate_exceeded`	Espere `details.retry_after` segundos.

Listar links

GET /links (escopo links:read). Filtros: tag, campaign_id, external_id, status, domain, search (título, destino ou código), created_from, created_to, sort (created_at ou total_clicks), limit (até 100) e cursor.

curl "https://api.curtei.com/v1/links?tag=newsletter&limit=50" \
  -H "Authorization: Bearer $CURTEI_TOKEN"

Obter, editar e apagar

Rota	Uso
`GET /links/{id}`	Um link pelo id
`GET /links/by-external-id/{external_id}`	Um link pelo seu identificador
`PATCH /links/{id}`	Muda `url`, `title`, `expires_at`, `max_clicks`, `status` (`active`/`disabled`), `tags`, `utm`, `metadata`, `password`, `rules`, `variants`. O `slug` não muda.
`DELETE /links/{id}`	Apaga. O código fica reservado por 90 dias.

Trocar a url de um link já divulgado é o jeito de mudar o destino sem trocar o link curto nem reimprimir o QR Code. A nova URL passa pela mesma checagem de segurança.