Cosa farai
- Emettere una chiave API con scope da Impostazioni → Chiavi API — il token viene mostrato una sola volta, 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 in modo che i tentativi successivi non creino mai link duplicati.
L'API di Elido è REST + JSON, documentata con OpenAPI 3.1 e limitata per chiave. Forniamo SDK di prima parte per TypeScript, Go e Python che la integrano. Il server MCP in @elido/mcp-server espone la stessa interfaccia agli agenti AI.
Rilasciare una chiave API#
- Impostazioni → Chiavi API → Crea chiave.
- Scegli un nome (consigliamo il sistema che la utilizzerà:
zapier,internal-billing,marketing-cli). - Scegli gli scope. I quattro più comuni:
links:read— elenca ed ispeziona i link.links:write— crea, aggiorna, elimina link.analytics:read— interroga gli eventi di click.webhooks:write— gestisci le iscrizioni ai webhook.
- Clicca su Crea. La chiave viene mostrata una sola volta — noi memorizziamo 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 per Go e Python seguono la stessa struttura. 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 velocità (Rate limits)#
Il piano gratuito offre 60 richieste al minuto per chiave. Pro: 600/min. Business: 6000/min. Il burst è il doppio del limite a regime; l'intestazione della risposta X-RateLimit-Remaining ti indica la tua situazione attuale.
Se raggiungi il limite, l'API restituisce 429 con Retry-After impostato. Gli SDK implementano di default il riprovo con backoff esponenziale — disattivalo se la tua applicazione gestisce la propria politica di riprovo.
Idempotenza#
Gli endpoint di modifica accettano un'intestazione Idempotency-Key. Passa un UUID per ogni scrittura prevista; memorizziamo la risposta per 24 ore in modo che i tentativi successivi (errori di rete, timeout ambigui) non creino duplicati.
Gli SDK aggiungono l'intestazione automaticamente. Se usi curl direttamente, genera la chiave lato client e includila in ogni tentativo.
Webhooks#
Per notifiche in tempo reale invece del polling, imposta i webhook sotto Impostazioni → Webhooks — inviamo eventi link.created, link.clicked.aggregated e domain.verified con firme HMAC.