X

Developer API

XURL API Documentation

Build against XURL with predictable authentication, clear endpoint contracts, and robust examples for production integrations.

Base URL: https://xurl.eu.cc/api/v1API Keys: /dashboard/api

Section

Introduction

Introduction

Understand the XURL Developer API surface and where requests are served from.

XURL Developer API lets you create, list, and analyze short links programmatically.

Base URL

https://xurl.eu.cc/api/v1

Key management

/dashboard/api

Enable API access from Dashboard before using API keys in production workloads.

Response Format

All endpoints return JSON payloads for both success and failures.

Error responses consistently use {"error": "message"} and standard HTTP status codes.

Plan Access

API key access is controlled by plan capability and API enablement status.

  • Business, Enterprise, and Big Enterprise can enable API access.
  • Expired plans fall back to free plan behavior and API access is blocked.
  • Disabled API keys return 403 with an access-not-enabled error.

Quick Start

Make your first authenticated API request in under a minute.

Start by creating an API key in Dashboard and sending a POST request to create a short link.

Get an API Key

  1. Open /dashboard/api
  2. Generate or rotate your API key
  3. Store it in a secret manager and never expose it client-side

Send First Request

POST/api/v1/links

Create a short link for the authenticated user.

Source files

app/api/v1/links/route.ts (POST)

lib/api/auth.ts (authenticateApiRequest)

curl · bash
curl https://xurl.eu.cc/api/v1/links \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

Authentication

All documented endpoints require Bearer API key authentication.

Authentication is validated via hashed API keys and plan checks before request handling.

Required Header

Authorization Header · http
Authorization: Bearer xurl_sk_live_xxxxxxxxx

Validation Rules

  • Missing or malformed Bearer token returns 401 Invalid API key.
  • Unknown key hash returns 401 Invalid API key.
  • Disabled or unsupported plan returns 403 API access is not enabled for your current plan.
  • Quota exhaustion returns 403 API quota exceeded.

Quota Side Effect

Every successful authentication increments API request usage before endpoint logic executes.

Create Link

Create a short URL with optional title and custom slug.

POST/api/v1/links

Create a short link for the authenticated user.

Source files

app/api/v1/links/route.ts (POST)

lib/api/auth.ts (authenticateApiRequest)

Request Body

The url field is required. title and customSlug are optional.

Create Link Request · json
{
  "url": "https://example.com",
  "title": "Launch page",
  "customSlug": "launch"
}

Successful Response

Create Link Response · json
{
  "id": "launch",
  "shortUrl": "https://xurl.eu.cc/launch",
  "url": "https://example.com",
  "createdAt": 1710000000000
}

Error Cases

  • 400 when url is missing or malformed.
  • 403 for plan restrictions or quota limits.
  • 409 when customSlug is already taken.
  • 429 when upstream rate limit is exceeded.

List Links

Fetch paginated links created by the authenticated user.

GET/api/v1/links

List authenticated user links with cursor pagination.

Source files

app/api/v1/links/route.ts (GET)

lib/api/auth.ts (authenticateApiRequest)

Query Parameters

  • limit: integer from 1 to 100 (default 20)
  • cursor: createdAt timestamp from previous response
List Links with Pagination · bash
curl "https://xurl.eu.cc/api/v1/links?limit=20&cursor=1710000000000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Shape

List Links Response · json
{
  "data": [
    {
      "id": "launch",
      "shortUrl": "https://xurl.eu.cc/launch",
      "url": "https://example.com",
      "title": "Launch page",
      "clicks": 42,
      "createdAt": 1710000000000,
      "expiresAt": null,
      "status": "active"
    }
  ],
  "pagination": {
    "limit": 20,
    "nextCursor": 1710000000000,
    "hasMore": true
  }
}

Status Field

  • active when link is enabled and not expired
  • deactivated when isActive is false
  • expired when expiresAt is in the past

Analytics

Retrieve per-link click trends and country breakdown summaries.

GET/api/v1/links/{id}/analytics

Fetch analytics timeline and geo summary for a link owned by the API key owner.

Source files

app/api/v1/links/[id]/analytics/route.ts (GET)

lib/api/auth.ts (authenticateApiRequest)

Ownership Rules

  • 404 when the provided link slug does not exist.
  • 403 when the slug exists but belongs to another user.
  • 200 with analytics payload for owned links.

Response Example

Analytics Response · json
{
  "id": "launch",
  "clicks": 42,
  "countries": ["US", "IN"],
  "timeline": [
    {
      "date": "2026-03-14",
      "clicks": 12,
      "uniqueVisitors": 10
    }
  ]
}

Data Window

The current endpoint returns a 30-day timeline with daily clicks and unique visitors.

Quota Limits

Understand plan limits and quota-exhaustion behavior.

Business

500

total API requests per active purchase

Enterprise

5000

total API requests per active purchase

Enforcement

When quota is exhausted, requests fail with HTTP 403 and API quota exceeded.
Quota Exceeded · json
{
  "error": "API quota exceeded"
}

Usage Tracking

Quota usage and totals are captured on each request and can be surfaced in request logs.

Errors

Common failure responses and troubleshooting pointers.

Every error payload follows a lightweight JSON shape to simplify client-side handling.

Payload Format

Invalid API Key · json
{
  "error": "Invalid API key"
}
Quota Exceeded · json
{
  "error": "API quota exceeded"
}

Common Status Codes

  • 400 validation failure
  • 401 invalid API key
  • 403 plan disabled, unauthorized resource, or quota exceeded
  • 404 link not found
  • 409 duplicate custom slug
  • 429 rate limit exceeded
  • 500 unexpected server failure

Debugging Checklist

  1. Confirm API key and plan status in /dashboard/api
  2. Verify you are calling /api/v1 routes with a Bearer header
  3. Check request body JSON and required fields
  4. Inspect returned error message and status code

Code Examples

Production-ready examples for curl, JavaScript, and Node.js.

Use these snippets as a starting point and inject API keys from your secure runtime environment.

curl

curl · bash
curl https://xurl.eu.cc/api/v1/links \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

JavaScript

JavaScript · javascript
const response = await fetch("https://xurl.eu.cc/api/v1/links", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    url: "https://example.com",
    title: "Launch page"
  })
});

const data = await response.json();
console.log(data);

Node.js

Node.js · javascript
import fetch from "node-fetch";

const response = await fetch("https://xurl.eu.cc/api/v1/links", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ url: "https://example.com" })
});

console.log(await response.json());