Chaves de API e guia rápido do SDK

A API do Elido é REST + JSON, documentada com OpenAPI 3.1 e com limite de taxa por chave. Oferecemos SDKs próprios para TypeScript, Go e Python que a encapsulam. O servidor MCP em @elido/mcp-server expõe a mesma superfície para agentes de IA.

Emitir uma chave de API

1. Settings → API keys → Create key.
2. Escolha um nome (recomendamos o do sistema que vai usá-la: zapier, internal-billing, marketing-cli).
3. Escolha os escopos. Os quatro mais comuns:
   • links:read: listar e inspecionar links.
   • links:write: criar, atualizar e excluir links.
   • analytics:read: consultar eventos de clique.
   • webhooks:write: gerenciar assinaturas de webhooks.
4. Clique em Create. A chave é exibida uma única vez: guardamos apenas um hash.

Se você perder uma chave, revogue-a na mesma página e emita uma nova. As chaves revogadas são rejeitadas em até 60 segundos em todas as regiões.

Guia rápido com o SDK de TypeScript

import { ElidoClient } from "@elido/sdk";

const client = new ElidoClient({ apiKey: process.env.ELIDO_API_KEY! });

const link = await client.links.create({
  destination: "https://acme.com/spring-sale",
  slug: "spring-2026",
});

console.log(link.short_url);

Os SDKs de Go e Python seguem o mesmo formato. Referência completa em /api.

Guia rápido com curl

curl -X POST https://api.elido.app/v1/links \
  -H "Authorization: Bearer $ELIDO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"destination":"https://acme.com/spring-sale","slug":"spring-2026"}'

Limites de taxa

O plano gratuito tem 60 requisições por minuto por chave. Pro: 600/min. Business: 6000/min. O burst é 2 vezes o limite em regime estável; o cabeçalho de resposta X-RateLimit-Remaining mostra quanto ainda resta.

Se você atingir o limite, a API retorna 429 com Retry-After. Os SDKs implementam por padrão novas tentativas com backoff exponencial: desative isso se o seu app gerencia a própria política de novas tentativas.

Idempotência

Os endpoints que alteram dados aceitam um cabeçalho Idempotency-Key. Passe um UUID para cada escrita pretendida; guardamos a resposta em cache por 24 horas para que as novas tentativas (erros de rede, timeouts ambíguos) não criem duplicatas.

Os SDKs adicionam o cabeçalho automaticamente. Se você usa curl diretamente, gere a chave no cliente e inclua-a em cada nova tentativa.

Webhooks

Para receber notificações em tempo real em vez de fazer polling, configure webhooks em Settings → Webhooks: entregamos eventos como link.created, link.updated e domain.verified com assinaturas HMAC. Os eventos por clique ainda não estão disponíveis; veja o guia de webhooks para a lista completa.