Skip to main content
Get up and running with Dubly by creating your first short link.

​
Prerequisites

  • Dubly installed and running (see Installation)
  • Your API password from the install script or .env file
  • A domain pointed to your server
1

Verify Dubly is running

Check that the API responds:
curl https://dubly.example.com/api/links \
  -H "X-API-Key: your-secret-key"
You should see an empty array [] or a JSON list of links.
2

Create a short link

Use the API to create your first link:
curl -X POST https://dubly.example.com/api/links \
  -H "X-API-Key: your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "dubly.example.com",
    "destination": "https://github.com/scmmishra/dubly",
    "title": "Dubly on GitHub",
    "slug": "gh"
  }'
Response:
{
  "id": 1,
  "domain": "dubly.example.com",
  "slug": "gh",
  "destination": "https://github.com/scmmishra/dubly",
  "title": "Dubly on GitHub",
  "tags": "",
  "is_active": true,
  "created_at": "2026-03-02T10:30:00Z",
  "updated_at": "2026-03-02T10:30:00Z"
}
The slug field is optional. If omitted, Dubly generates a random 6-character slug using crypto/rand.
3

Test the redirect

Visit your short link in a browser or curl it:
curl -I https://dubly.example.com/gh
You should see a 302 Found redirect to your destination:
HTTP/2 302
location: https://github.com/scmmishra/dubly
4

View analytics

Open the admin UI to see click analytics:
https://dubly.example.com/admin/links
Click on your link to see detailed analytics including:
  • Click count over time
  • Geographic distribution (if GeoIP is configured)
  • Browser and device breakdown
  • Referrer sources

​
Using the admin UI

Dubly includes a built-in admin interface for managing links without the API.
1

Access the admin UI

Navigate to https://your-domain.com/admin/loginEnter your API password to log in.
2

Create a link via UI

Click “New Link” and fill in:
  • Domain (select from configured domains)
  • Destination URL
  • Custom slug (optional)
  • Title and tags (optional)
Click “Create” to save.
3

Manage existing links

From the dashboard:
  • Edit link destinations or slugs
  • View click analytics
  • Deactivate links (returns 410 Gone instead of redirecting)
  • Delete links (soft delete, preserves analytics)

​
API examples

​
Auto-generated slug

Omit the slug field to generate a random 6-character identifier: 
curl -X POST https://dubly.example.com/api/links \
  -H "X-API-Key: your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "short.io",
    "destination": "https://example.com/some/long/url",
    "title": "Example Link",
    "tags": "demo,test"
  }'
Response might include "slug": "a7k3mn".

​
Multiple domains

If you configured multiple domains during installation, you can create links on any of them: 
# Link on primary domain
curl -X POST https://dubly.example.com/api/links \
  -H "X-API-Key: your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "dubly.example.com",
    "destination": "https://example.com/admin",
    "slug": "admin"
  }'

# Link on secondary domain
curl -X POST https://dubly.example.com/api/links \
  -H "X-API-Key: your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "short.io",
    "destination": "https://example.com/marketing",
    "slug": "promo"
  }'
Retrieve all links with pagination and search: 
# First 25 links
curl "https://dubly.example.com/api/links?limit=25&offset=0" \
  -H "X-API-Key: your-secret-key"

# Search by title, destination, or slug
curl "https://dubly.example.com/api/links?search=github" \
  -H "X-API-Key: your-secret-key"
Change the destination or other properties: 
curl -X PATCH https://dubly.example.com/api/links/1 \
  -H "X-API-Key: your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"destination": "https://example.com/new-url"}'
Updating a link automatically invalidates the redirect cache. The new destination takes effect immediately.
Deactivated links return 410 Gone instead of redirecting: 
curl -X PATCH https://dubly.example.com/api/links/1 \
  -H "X-API-Key: your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'
Test it: 
curl -I https://dubly.example.com/gh
# HTTP/2 410
Dubly uses soft deletes, so analytics are preserved: 
curl -X DELETE https://dubly.example.com/api/links/1 \
  -H "X-API-Key: your-secret-key"
Deleted links behave the same as deactivated links (410 Gone).

​
How redirects work

Dubly treats any request that doesn’t match /api/* or /admin/* as a potential redirect.
1

Domain and slug extraction

The domain comes from the Host header, the slug from the request path:
https://short.io/custom-slug
Host: short.io
Slug: custom-slug
2

Cache lookup

Dubly checks an in-memory LRU cache (default 10,000 entries) for the domain/slug pair.
3

Database fallback

If not cached, it queries SQLite:
SELECT id, destination, is_active 
FROM links 
WHERE domain = ? AND slug = ? AND is_active = 1
4

Response

  • Active link: 302 redirect to destination
  • Inactive/deleted: 410 Gone
  • Not found: 404 Not Found
5

Analytics collection

The redirect handler pushes click events to a buffered collector, which records:
  • Timestamp, IP, referer
  • User-Agent (parsed for browser/OS/device)
  • Geographic data (if GeoIP configured)
Bots and datacenter IPs are filtered automatically.

​
Next steps

Configuration

Explore all environment variables and tuning options

API Reference

Complete API documentation with all endpoints

Analytics

Learn how click tracking and bot filtering works

Custom Domains

Set up multiple short domains for different use cases

Build docs developers (and LLMs) love

Get started for freeTalk to us