URL Shortener API: Automate and Integrate with URLW

A URL shortener you use only through a web interface is a convenience tool. A URL shortener with a clean API is an infrastructure component — something you can embed in your application, automate in your CI/CD pipeline, trigger from your CRM, or use to generate thousands of links in a batch job. The URLW REST API is designed for developers who want to integrate link shortening into their workflows without friction.

Authentication

The URLW API uses Bearer token authentication. Generate your API token in your URLW dashboard under Settings → API Keys. Each token is scoped to your account and carries the permissions of the account that created it.

Include your token in the Authorization header of every request:

Authorization: Bearer YOUR_API_TOKEN

Keep your API token secret. Do not commit it to version control. Use environment variables or a secrets manager in production environments.

Core Endpoints

The URLW API follows REST conventions. All endpoints accept and return JSON. The base URL is https://urlw.fr/api/v1.

• POST /links — Create a new short link
• GET /links — List all your short links (paginated)
• GET /links/{id} — Retrieve a specific link and its metadata
• PATCH /links/{id} — Update a link (target URL, slug, expiry)
• DELETE /links/{id} — Delete a link
• GET /links/{id}/stats — Retrieve click statistics for a link
• GET /account — Retrieve your account information and usage

Creating Your First Short Link via API

Here is a minimal example using curl to create a short link:

curl -X POST https://urlw.fr/api/v1/links \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://yourwebsite.com/landing-page",
"slug": "summer-promo",
"domain": "urlw.fr"
}'

A successful response returns a 201 Created status with the created link object:

{
"id": "lnk_abc123",
"short_url": "https://urlw.fr/summer-promo",
"original_url": "https://yourwebsite.com/landing-page",
"slug": "summer-promo",
"created_at": "2024-06-01T10:00:00Z",
"clicks": 0
}

Rate Limits

API rate limits depend on your plan. Starter plans allow up to 60 requests per minute. Pro plans allow up to 300 requests per minute. Business plans offer higher limits on request. Rate limit headers are included in every API response:

• X-RateLimit-Limit — Your plan's requests-per-minute limit
• X-RateLimit-Remaining — Requests remaining in the current window
• X-RateLimit-Reset — Unix timestamp when the window resets

If you exceed your rate limit, the API returns a 429 Too Many Requests response. Implement exponential backoff in your client code to handle this gracefully.

Error Handling

The API uses standard HTTP status codes. Errors return a JSON body with a code and message field:

{
"code": "slug_taken",
"message": "The slug 'summer-promo' is already in use."
}

Common error codes: invalid_url (the target URL is malformed), slug_taken (the requested slug is unavailable), rate_limited (too many requests), unauthorized (invalid or missing API token).

Full API Documentation

The complete API reference — including all parameters, response schemas, pagination details, webhook documentation, and SDK examples — is available at /en/docs/api. Start building at /en/register and review plans at /en/#pricing.