Riferimento API REST

Autenticazione

L'API URLW usa chiavi API per l'autenticazione. Ogni richiesta deve includere la tua chiave nell'header Authorization.

Comment obtenir une clé API

1. Connectez-vous à votre compte URLW et accédez à la page Clés API
2. Donnez un nom à votre clé et cliquez sur Créer
3. Copiez la clé affichée — elle ne sera plus visible ensuite

Header richiesti

Authorization: Bearer uw_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

POST/api/links

Crea un nuovo link breve. Richiede una chiave API valida.

Header richiesti

Authorization: Bearer uw_votre_cle_api
Content-Type: application/json

Body della richiesta

{
  "url": "https://example.com/une-url-tres-longue"
}

Risposta (201 Created)

{
  "id": 42,
  "short_code": "aB3xYz",
  "short_url": "https://urlw.fr/aB3xYz",
  "original_url": "https://example.com/une-url-tres-longue",
  "clicks": 0,
  "created_at": "2026-04-18T12:00:00+00:00"
}

Esempio curl

curl -s -X POST https://urlw.fr/api/links \
  -H "Authorization: Bearer uw_votre_cle_api" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/page-longue?utm_source=api"}'

GET/api/links

Elenca tutti i tuoi link brevi. Richiede una chiave API valida.

Esempio curl

curl -s https://urlw.fr/api/links \
  -H "Authorization: Bearer uw_votre_cle_api" | jq .

Risposta (200 OK)

[
  {
    "id": 42,
    "short_code": "aB3xYz",
    "short_url": "https://urlw.fr/aB3xYz",
    "original_url": "https://example.com/page-longue",
    "clicks": 14,
    "created_at": "2026-04-18T12:00:00+00:00"
  }
]

GET/api/links/{id}

Recupera i dettagli di un link specifico, incluso il contatore di clic.

Esempio curl

curl -s https://urlw.fr/api/links/42 \
  -H "Authorization: Bearer uw_votre_cle_api" | jq .

Risposta (200 OK)

{
  "id": 42,
  "short_code": "aB3xYz",
  "short_url": "https://urlw.fr/aB3xYz",
  "original_url": "https://example.com/page-longue",
  "clicks": 14,
  "created_at": "2026-04-18T12:00:00+00:00"
}

DELETE/api/links/{id}

Elimina definitivamente un link. Il reindirizzamento sarà immediatamente inattivo. Questa azione è irreversibile.

Esempio curl

curl -s -X DELETE https://urlw.fr/api/links/42 \
  -H "Authorization: Bearer uw_votre_cle_api"
# → 204 No Content (successo, nessun body)

6. Codici di errore

Formato errore

{
  "error": "authentication_failed",
  "message": "Invalid or expired API key."
}

Esempi PHP & JavaScript

Non è necessario alcun SDK: l'API è una semplice API REST JSON. Ecco esempi copia-incolla per i linguaggi più comuni.

PHP

<?php
// URLW API — PHP example (no SDK needed)
$apiKey = 'uw_votre_cle_api';
$url    = 'https://example.com/une-url-tres-longue';

$ch = curl_init('https://urlw.fr/api/links');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['url' => $url]),
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

echo $response['shortUrl'];
// => https://urlw.fr/aB3xYz

JavaScript (Node.js / fetch)

const API_KEY = 'uw_votre_cle_api';

const res = await fetch('https://urlw.fr/api/links', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ url: 'https://example.com/une-url-tres-longue' }),
});

const link = await res.json();
console.log(link.shortUrl);
// => https://urlw.fr/aB3xYz

Link con slug personalizzato (Pro+)

curl -s -X POST https://urlw.fr/api/links \
  -H "Authorization: Bearer uw_votre_cle_api" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/promo","customSlug":"ma-promo"}'

{
  "id": 43,
  "short": "rT9kWm",
  "customSlug": "ma-promo",
  "shortUrl": "https://urlw.fr/ma-promo",
  "url": "https://example.com/promo",
  "clickCount": 0,
  "createdAt": "2026-04-25T14:00:00+00:00"
}

Gli slug personalizzati richiedono un piano Pro o superiore. Da 3 a 60 caratteri, lettere, cifre e trattini.