API Reference

The Urlytics API allows you to programmatically create and manage links, retrieve analytics, and integrate link tracking into your applications.

Introduction

The Urlytics API is organised around REST principles. It accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and methods.

Base URL: All API requests should be made to https://api.urlytics.co.uk/v1

Authentication

The Urlytics API uses API keys to authenticate requests. You can view and manage your API keys in your dashboard settings.

Include your API key in the Authorization header of all requests:

Authorization: Bearer your_api_key_here

Keep your API keys secure. Do not share them in public repositories or client-side code. If you believe a key has been compromised, regenerate it immediately.

Rate Limits

API requests are rate limited to ensure fair usage and system stability:

Plan	Requests per minute	Requests per day
Free	60	1,000
Pro	600	100,000
Enterprise	Custom	Custom

Rate limit information is included in response headers:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599
X-RateLimit-Reset: 1704067200
            

Error Handling

The API uses standard HTTP status codes to indicate success or failure:

200 OK - Request succeeded

201 Created - Resource created successfully

400 Bad Request - Invalid parameters

401 Unauthorised - Invalid or missing API key

403 Forbidden - Insufficient permissions

404 Not Found - Resource does not exist

429 Too Many Requests - Rate limit exceeded

500 Server Error - Something went wrong

Error responses include a JSON body with details:

{
  "error": {
    "code": "invalid_url",
    "message": "The provided URL is not valid",
    "param": "destination"
  }
}
            

Create Link

POST /links

Create a new tracked short link.

Request Body

Parameter	Type	Description
`destination`required	string	The URL to redirect to
`slug`	string	Custom slug (auto-generated if not provided)
`domain`	string	Custom domain (defaults to urlytics.co.uk)
`title`	string	Link title for dashboard organisation
`expires_at`	string	ISO 8601 expiration date
`password`	string	Password to protect the link

Example Request

curl -X POST https://api.urlytics.co.uk/v1/links \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "https://example.com/long-url",
    "slug": "my-link",
    "title": "Marketing Campaign Q1"
  }'
                    

Example Response

{
  "id": "lnk_a1b2c3d4",
  "short_url": "https://urlytics.co.uk/my-link",
  "destination": "https://example.com/long-url",
  "slug": "my-link",
  "domain": "urlytics.co.uk",
  "title": "Marketing Campaign Q1",
  "clicks": 0,
  "created_at": "2025-01-06T12:00:00Z"
}
                    

Get Link

GET /links/{id}

Retrieve details for a specific link by its ID.

Path Parameters

Parameter	Type	Description
`id`required	string	The link ID (e.g., lnk_a1b2c3d4)

List Links

GET /links

Retrieve a paginated list of all your links.

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of results (default: 20, max: 100)
`offset`	integer	Pagination offset (default: 0)
`domain`	string	Filter by domain
`search`	string	Search by title or destination
`sort`	string	Sort by: created_at, clicks (default: created_at)
`order`	string	Order: asc, desc (default: desc)

Update Link

PUT /links/{id}

Update an existing link's destination, title, or settings.

Request Body

Parameter	Type	Description
`destination`	string	New destination URL
`title`	string	New title
`expires_at`	string	New expiration date (null to remove)
`password`	string	New password (null to remove)
`archived`	boolean	Archive or unarchive the link

Delete Link

DELETE /links/{id}

Permanently delete a link and all associated analytics data.

Warning: This action cannot be undone. All click data will be permanently lost.

Link Statistics

GET /links/{id}/stats

Retrieve aggregated statistics for a link.

Query Parameters

Parameter	Type	Description
`period`	string	Time period: 24h, 7d, 30d, 90d, all (default: 30d)

Example Response

{
  "total_clicks": 4521,
  "unique_visitors": 3892,
  "top_countries": [
    { "country": "GB", "clicks": 1823 },
    { "country": "US", "clicks": 1204 }
  ],
  "top_referrers": [
    { "referrer": "twitter.com", "clicks": 892 }
  ],
  "devices": {
    "mobile": 2341,
    "desktop": 1980,
    "tablet": 200
  },
  "clicks_by_day": [
    { "date": "2025-01-06", "clicks": 156 }
  ]
}
                    

Click Events

GET /links/{id}/events

Retrieve individual click events for a link (Pro plan only).

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of results (default: 50, max: 500)
`offset`	integer	Pagination offset
`start_date`	string	Filter from date (ISO 8601)
`end_date`	string	Filter to date (ISO 8601)

Geographic Data

GET /links/{id}/geo

Retrieve geographic breakdown of clicks by country and city.

List Domains

GET /domains

List all custom domains configured for your account.

Add Domain

POST /domains

Add a new custom domain to your account (Pro plan only).

Request Body

Parameter	Type	Description
`domain`required	string	The domain to add (e.g., links.example.com)

Verify Domain

POST /domains/{id}/verify

Trigger DNS verification for a pending domain.