API Reference

Click analytics and A/B testing for growth

Getting Started

Introduction

LinkForge’s REST API gives developers programmatic access to create, manage, and analyze shortened URLs at scale. Authenticate using your private API key via the Authorization: Bearer <token> header. All requests must be made over HTTPS to https://api.linkforge.io/v1.

Rate limits are set to 1,200 requests per minute for Standard plans and 5,000 requests per minute for Enterprise accounts. Response payloads are returned in JSON format with consistent error structures. Need to integrate link shortening into your CRM, newsletter platform, or custom dashboard? Our API handles UTM parameter injection, geographic targeting, and real-time click tracking out of the box.

Authentication

Generate your API key in Dashboard > Settings > Developers. Keys are scoped to read/write or read-only access and support IP allowlisting.

Base URL

All endpoints route through https://api.linkforge.io/v1. Sandbox environments use https://api-sandbox.linkforge.io/v1 for safe testing.

Error Handling

HTTP status codes follow REST conventions. 401 indicates invalid credentials, 429 signals rate limiting, and 404 means the resource was not found. All errors return a JSON body with error_code and message.

Endpoints

Core Methods

Manage your link infrastructure with these primary endpoints. Each method supports pagination, filtering, and webhook triggers on state changes.

POST /links

Create a new shortened URL. Accepts destination, custom_alias (optional), utm_source, utm_medium, utm_campaign, and expiration_date. Returns the short_url, qr_code_url, and analytics_dashboard_url.

PATCH /links/{id}

Update an existing link. Modify the destination URL, toggle active status, or adjust redirect behavior (301 vs 302). Changes propagate globally within 2 seconds via our edge network.

DELETE /links/{id}

Permanently remove a link and halt all traffic redirection. Archived click data remains accessible for 90 days before permanent deletion. Returns 204 No Content on success.

GET /analytics/{id}

Retrieve granular click statistics. Parameters include start_date, end_date, granularity (hourly/daily/monthly), and metrics (clicks, unique_visitors, referrers, devices, geolocations).

Code Examples

Integration Samples

Copy-paste ready snippets to spin up your first integration in under five minutes. We provide official clients for Python, JavaScript/Node.js, Go, and Ruby.

Python

import requests

headers = {"Authorization": "Bearer lf_live_8xK9mP2vQ"}
payload = {
    "destination": "https://shop.example.com/summer-sale",
    "utm_campaign": "email_q3",
    "utm_source": "newsletter"
}
res = requests.post("https://api.linkforge.io/v1/links", json=payload, headers=headers)
print(res.json()["short_url"])

JavaScript (Node.js)

const axios = require('axios');

const response = await axios.get('https://api.linkforge.io/v1/analytics/lnk_4f9a2c', {
    headers: { 'Authorization': 'Bearer lf_live_8xK9mP2vQ' },
    params: { start_date: '2024-01-01', granularity: 'daily' }
});
console.log(response.data.metrics.clicks);

cURL

curl -X PATCH https://api.linkforge.io/v1/links/lnk_4f9a2c \
  -H "Authorization: Bearer lf_live_8xK9mP2vQ" \
  -H "Content-Type: application/json" \
  -d '{"destination": "https://shop.example.com/new-landing", "active": true}'