REST API Reference

Authentication

The URLW API uses API keys for authentication. Each request must include your key in the Authorization header.

How to get an API key

1. Log in to your URLW account and go to the API Keys page
2. Name your key and click Create
3. Copy the displayed key — it won't be shown again

Required headers

Authorization: Bearer uw_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

POST/api/links

Create a new short link. Requires a valid API key.

Required headers

Authorization: Bearer uw_votre_cle_api
Content-Type: application/json

Request body

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

Response (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"
}

curl example

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

List all your short links. Requires a valid API key.

curl example

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

Response (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}

Get details of a specific link, including the click counter.

curl example

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

Response (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}

Permanently delete a link. The redirect will be immediately inactive. This action is irreversible.

curl example

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

6. Error codes

Error format

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

PHP & JavaScript Examples

No SDK needed: the API is a simple JSON REST API. Here are copy-paste examples for the most common languages.

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 with custom slug (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"
}

Custom slugs require a Pro plan or higher. 3 to 60 characters, letters, numbers and hyphens.