Inizia

Riferimento API

Crea e gestisci link brevi in modo programmatico. Ogni richiesta richiede un token Bearer dalla schermata delle chiavi API nella tua dashboard.

Autenticazione

Invia la chiave come bearer token a ogni richiesta.

URL di basehttps://urlvis.com

Creare un link

Crea un nuovo link breve. La destinazione viene analizzata dal filtro antifrode al momento della creazione: la scrittura è più lenta di un accorciatore semplice.

POST/api/linkslinks:write
curl -X POST https://urlvis.com/api/links \
  -H "Authorization: Bearer urlvis_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "https://example.com/campaign",
    "domainId": "<domain-uuid>",
    "slug": "spring",
    "expiresAt": "2026-12-31T23:59:00.000Z"
  }'

destination, domainId — required · slug, expiresAt — optional

Elencare i link

Restituisce tutti i link del tuo account.

GET/api/linkslinks:read
curl https://urlvis.com/api/links \
  -H "Authorization: Bearer urlvis_live_..."

Modificare la destinazione di un link

Aggiorna dove punta un link esistente. Il link breve, il suo QR code e la cronologia dei clic rimangono uguali. La nuova destinazione passa dallo stesso controllo di sicurezza di un link nuovo, quindi può restituire 422 blocked_by_filter.

PATCH/api/links/{id}links:write
curl -X PATCH https://urlvis.com/api/links/<link-id> \
  -H "Authorization: Bearer urlvis_live_..." \
  -H "Content-Type: application/json" \
  -d '{"destination": "https://example.com/new-target"}'

destination — required · utm — optional. The short link, its QR code and click history stay the same. The new destination runs through the same security scan as a new link, so this can return 422 blocked_by_filter.

Eliminare un link

Rimuove un link dal tuo account. Restituisce 204 in caso di successo, 404 se il link non esiste.

DELETE/api/links/{id}links:write
curl -X DELETE https://urlvis.com/api/links/<link-id> \
  -H "Authorization: Bearer urlvis_live_..."

204 on success, 404 if no such link exists on your account.

Esportare le statistiche

Esporta le statistiche dei clic in CSV. Filtro opzionale per linkId. La durata di conservazione dipende dal tuo piano.

GET/api/analytics/export?linkId=links:read
curl "https://urlvis.com/api/analytics/export?linkId=<link-uuid>" \
  -H "Authorization: Bearer urlvis_live_..." \
  -o analytics.csv

Limiti di frequenza

Ogni risposta riporta la quota rimanente. I limiti sono per chiave, non per indirizzo IP.

X-RateLimit-Limit: 60       # links:write
X-RateLimit-Limit: 600      # links:read
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 42        # seconds
Retry-After: 42              # 429 only

Errori

Gli errori sono restituiti in JSON con un campo error e lo stato HTTP corrispondente.

401 invalid_api_key      key unknown, revoked, or plan no longer includes API
403 insufficient_scope   key lacks the scope this endpoint needs
404 not_found            no such link on this account
422 blocked_by_filter    destination rejected by the fraud filter
402 link_quota           monthly plan quota exhausted
429 rate_limited         see Retry-After

Ottenere il tuo ID dominio

L'endpoint POST /api/links richiede un domainId. Attualmente non esiste un endpoint API per elencare i tuoi domini — l'endpoint domains richiede una sessione della dashboard. Per ottenere il tuo ID dominio:

  1. Apri la dashboard e vai su Domini.
  2. Ogni scheda di dominio mostra il suo ID con un pulsante di copia accanto — copialo da lì.