API

Crea e gestisci link corti da script e app. L'API è gratuita. Crea una chiave nella tua dashboard alla voce Chiavi API, poi inviala come bearer token.

Autenticazione

Authorization: Bearer gz_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Le chiavi vengono mostrate una sola volta. Trattale come password: chiunque abbia la tua chiave può creare e modificare link nel tuo account. Revoca dalla dashboard una chiave finita nelle mani sbagliate.

Limiti

• 60 richieste al minuto per chiave.
• 500 nuovi link al giorno per account.
• Le destinazioni vengono controllate con Google Safe Browsing e con la nostra blocklist. Altri servizi di accorciamento link non possono essere usati come destinazioni.

Creare un link

curl -X POST https://gozi.to/api/my/links \
  -H "Authorization: Bearer $GOZI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/launch", "code": "launch"}'

code è facoltativo (4–32 lettere, numeri, - o _). Omettilo per un codice casuale di 7 caratteri. Risposta 201:

{
  "link": {
    "code": "launch",
    "shortUrl": "https://gozi.to/launch",
    "url": "https://example.com/launch",
    "status": "active",
    "statusReason": null,
    "custom": true,
    "createdAt": 1790000000000,
    "expiresAt": null
  }
}

Elencare i link

GET /api/my/links?limit=25&cursor=<nextCursor>&q=<search>&clicks=1

Dal più recente. Passa nextCursor della pagina precedente per ottenere la successiva. clicks=1 aggiunge i conteggi dei clic umani di sempre.

Leggere, modificare, eliminare

GET    /api/my/links/{code}
PATCH  /api/my/links/{code}   {"url": "https://new.example"}  or  {"status": "disabled" | "active"}
DELETE /api/my/links/{code}

Statistiche

GET /api/my/links/{code}/stats

Restituisce i clic umani degli ultimi 90 giorni e di sempre, i clic al giorno e i principali paesi, referrer, dispositivi, browser e sistemi operativi. I bot e le anteprime dei link (Slack, WhatsApp e simili) sono conteggiati a parte in botClicks. I risultati restano in cache per circa 5 minuti.

Errori

Gli errori usano i codici di stato HTTP e un corpo JSON:

{ "error": { "code": "slug_taken", "message": "That custom link is already taken." } }

• 400 dati non validi (invalid_url, invalid_slug, …)
• 401 chiave mancante, non valida o revocata
• 409 link personalizzato già occupato
• 422 destinazione non consentita (destination_blocked)
• 429 limite di frequenza o giornaliero raggiunto

Una descrizione leggibile dalle macchine di ogni endpoint si trova su /openapi.json.