API REST · v1 · grátis
API do curtei: encurte links pelo seu sistema
Crie links curtos, QR Codes e leia métricas de clique pela API REST do curtei. Chave de API, respostas em JSON e exemplos em cURL, JavaScript, PHP e Python.
A API do curtei é REST, fala JSON em UTF-8 e só aceita HTTPS. A base é https://api.curtei.com/v1. Ela é gratuita como o resto do curtei: a conta não tem plano pago nem cota mensal de links.
Primeiro link em 3 passos
- Crie uma conta grátis e confirme o e-mail. Sem a confirmação a conta só lê.
- Em Painel › Integrações, crie uma chave e escolha os escopos. O token (
<id>|wsk_live_...) aparece uma vez só: guarde num cofre de segredos. - Chame a API com o cabeçalho
Authorization: Bearer <token>.
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 Created:
{
"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"
}O que a API faz
| Recurso | O que dá para fazer | Página |
|---|---|---|
| Links | Criar, listar, buscar por external_id, editar, desativar e apagar. | Links |
| Lote | Até 1.000 links por chamada; até 50.000 em segundo plano. | Links em lote |
| Roteamento e A/B | Destino por país, estado, cidade, sistema, dispositivo ou idioma; variantes com peso. | Roteamento e A/B |
| QR Code | PNG ou SVG com cores, legenda e logo. | QR Code |
| Métricas | Resumo, série temporal, distribuição por dimensão, cliques e exportação CSV. | Métricas |
| Conversões | Postback servidor a servidor ou pixel, com receita por moeda. | Conversões |
| Webhooks | Eventos de clique, expiração e bloqueio, assinados com HMAC. | Webhooks |
| Domínios | Links no seu próprio domínio, com código personalizado. | Domínios |
| Páginas de links | A página /@usuario com os seus links agrupados. | Páginas de links |
| Campanhas | Agrupar links e somar as métricas. | Campanhas |
Limites e regras
| Item | Valor |
|---|---|
| Base da API | https://api.curtei.com/v1 |
| Requisições | 120 por minuto por conta (cabeçalhos X-RateLimit-Limit e X-RateLimit-Remaining) |
| Criação de links | 1.000 por hora e 5.000 por dia por conta (teto antiabuso; cada item de lote conta) |
Código personalizado (slug) | Só em domínio próprio |
| Idempotência | Idempotency-Key em todo POST, vale 24 h |
| Paginação | Por cursor: { "data": [...], "next_cursor": "..." } |
| Versão | No caminho (/v1). Mudança incompatível vira /v2, com 6 meses de convivência |
Usando uma IA para integrar
Cole https://curtei.com/llms-full.txt no ChatGPT, Claude, Cursor ou Copilot e peça a integração: o arquivo traz toda a API em texto puro. Cada página desta documentação também existe em Markdown, com .md no fim do endereço (por exemplo, /docs/api/links.md).