API keys and SDK quickstart

The Elido API is REST + JSON, OpenAPI 3.1 documented, and rate-limited per key. We ship first-party SDKs for TypeScript, Go, and Python that wrap it. The MCP server in @elido/mcp-server exposes the same surface to AI agents.

Issue an API key#

1. Settings → API keys → Create key.
2. Pick a name (we recommend the system that's going to use it: zapier, internal-billing, marketing-cli).
3. Pick scopes. The four common ones:
   • links:read — list and inspect links.
   • links:write — create, update, delete links.
   • analytics:read — query click events.
   • webhooks:write — manage webhook subscriptions.
4. Click Create. The key is shown once — we store only a hash.

If you lose a key, revoke it from the same page and issue a new one. Revoked keys are rejected within 60 seconds across all regions.

Quickstart with the TypeScript SDK#

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);

The Go and Python SDKs follow the same shape. Full reference at /api.

Quickstart with 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"}'

Rate limits#

The free tier gets 60 requests per minute per key. Pro: 600/min. Business: 6000/min. Burst is 2× the steady-state limit; the response header X-RateLimit-Remaining tells you where you stand.

If you hit the limit, the API returns 429 with Retry-After set. The SDKs implement exponential-backoff retry by default — turn it off if your app handles its own retry policy.

Idempotency#

Mutating endpoints accept an Idempotency-Key header. Pass a UUID per intended write; we cache the response for 24 hours so retries (network errors, ambiguous timeouts) don't double-create.

The SDKs add the header automatically. If you're using curl directly, generate the key client-side and include it on every retry.

Webhooks#

For real-time notifications instead of polling, set up webhooks under Settings → Webhooks — we deliver link.created, link.clicked.aggregated, and domain.verified events with HMAC signatures.