REST API v1

API Documentation

Integrate URL shortening into your applications with our powerful REST API. Manage everything programmatically.

Base URL

https://gf.to/api

All requests must include the Accept: application/json header.

Authentication

Authorization: Bearer 1|abc123...

1 URLs

Manage short URLs.

Get /api/urls

List all URLs. Supports pagination via ?page=1.

Example Response

{
    "data": [
        {
            "id": 1,
            "short_url": "https://gf.to/abc123",
            "original_url": "https://example.com/long-url",
            "short_code": "abc123",
            "title": "My Link",
            "clicks_count": 42,
            "max_clicks": null,
            "expires_at": null,
            "created_at": "2025-01-15T10:30:00Z"
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 5,
        "per_page": 15,
        "total": 72
    }
}

Post /api/urls

Create a new short URL.

Request Body

{
    "original_url": "url (required)",
    "title": "string (optional)",
    "max_clicks": "integer (optional)",
    "expires_at": "datetime (optional, format: Y-m-d H:i:s)"
}

Example Response

{
    "id": 1,
    "short_url": "https://gf.to/abc123",
    "original_url": "https://example.com/long-url",
    "short_code": "abc123",
    "title": "My Link",
    "clicks_count": 0,
    "max_clicks": null,
    "expires_at": null,
    "created_at": "2025-01-15T10:30:00Z"
}

Get /api/urls/{id}

Get details for a specific short URL.

Example Response

{
    "id": 1,
    "short_url": "https://gf.to/abc123",
    "original_url": "https://example.com/long-url",
    "short_code": "abc123",
    "title": "My Link",
    "clicks_count": 42,
    "max_clicks": null,
    "expires_at": null,
    "created_at": "2025-01-15T10:30:00Z"
}

Put/Patch /api/urls/{id}

Update an existing short URL.

Request Body

{
    "original_url": "url (optional)",
    "title": "string (optional)",
    "max_clicks": "integer (optional)",
    "expires_at": "datetime (optional, nullable)"
}

Delete /api/urls/{id}

Delete a short URL.

// Response: 204 No Content

2 Clicks & Stats

Retrieve click data and analytics for your short URLs.

Get /api/urls/{id}/clicks

Get paginated click events for a URL, including geolocation and device info.

Example Response

{
    "data": [
        {
            "id": 42,
            "ip": "203.0.113.1",
            "user_agent": "Mozilla/5.0 ...",
            "country": "US",
            "device_type": "mobile",
            "browser": "Chrome",
            "created_at": "2025-01-15T12:00:00Z"
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 10,
        "per_page": 15,
        "total": 142
    }
}

Get /api/urls/{id}/stats

Get aggregated statistics for a URL (top countries, devices, browsers, daily breakdown).

Example Response

{
    "total_clicks": 142,
    "countries": {
        "US": 85,
        "DE": 32,
        "GB": 25
    },
    "devices": {
        "mobile": 98,
        "desktop": 44
    },
    "browsers": {
        "Chrome": 72,
        "Safari": 40,
        "Firefox": 30
    },
    "daily": [
        { "date": "2025-01-15", "clicks": 12 },
        { "date": "2025-01-16", "clicks": 18 }
    ]
}