Cosa farai
- Emettere una chiave API con scope da Settings → API keys: il token viene mostrato una sola volta, quindi copialo subito.
- Accorciare un link con una sola chiamata SDK o un singolo comando
curlin meno di un minuto. - Usare le chiavi di idempotenza sulle richieste di modifica, così i nuovi tentativi non creano mai link duplicati.
L'API di Elido è REST + JSON, documentata con OpenAPI 3.1 e con limiti di frequenza per chiave. Forniamo SDK ufficiali per TypeScript, Go e Python che la incapsulano. Il server MCP in @elido/mcp-server espone la stessa interfaccia agli agenti AI.
Rilasciare una chiave API
- Settings → API keys → Create key.
- Scegli un nome (consigliamo il nome del sistema che la userà:
zapier,internal-billing,marketing-cli). - Scegli gli scope. I quattro più comuni:
links:read- elencare e consultare i link.links:write- creare, aggiornare ed eliminare i link.analytics:read- interrogare gli eventi di clic.webhooks:write- gestire le sottoscrizioni ai webhook.
- Fai clic su Create. La chiave viene mostrata una sola volta: conserviamo solo un hash.
Se perdi una chiave, revocala dalla stessa pagina e rilasciane una nuova. Le chiavi revocate vengono rifiutate entro 60 secondi in tutte le regioni.
Guida rapida con l'SDK 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);
Gli SDK Go e Python seguono la stessa struttura. Il riferimento completo è su /api.
Guida rapida con 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"}'
Limiti di frequenza
Il piano gratuito ha 60 richieste al minuto per chiave. Pro: 600/min. Business: 6000/min. Il burst è pari a 2× il limite a regime; l'header di risposta X-RateLimit-Remaining indica a che punto sei.
Se raggiungi il limite, l'API restituisce 429 con Retry-After impostato. Gli SDK implementano per impostazione predefinita un nuovo tentativo con backoff esponenziale: disattivalo se la tua app gestisce una propria politica di retry.
Idempotenza
Gli endpoint di modifica accettano un header Idempotency-Key. Passa un UUID per ogni scrittura prevista; conserviamo la risposta per 24 ore, così i nuovi tentativi (errori di rete, timeout ambigui) non creano duplicati.
Gli SDK aggiungono l'header automaticamente. Se usi curl direttamente, genera la chiave lato client e includila a ogni nuovo tentativo.
Webhook
Per ricevere notifiche in tempo reale invece di fare polling, configura i webhook in Settings → Webhooks: consegniamo eventi come link.created, link.updated e domain.verified con firme HMAC. Gli eventi per singolo clic non sono ancora disponibili; consulta la guida ai webhook per l'elenco completo.