API Documentation

The yourshortsite.link REST API lets you shorten URLs, generate QR codes, build UTM links, and retrieve stats — programmatically from any language or platform.

Base URL: https://yourshortsite.link/api/v1

Introduction

All API requests are made over HTTPS. Request bodies are JSON. Responses are always JSON (except the /qr endpoint which returns a PNG image).

Authentication

Every request must include your API key in the X-Api-Key header:

# Example with curl
curl https://yourshortsite.link/api/v1/shorten \
  -H "X-Api-Key: ysl_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/long-url"}'

You can also pass the key as a Bearer token in the Authorization header:

Authorization: Bearer ysl_your_api_key_here

Generate API keys from your account dashboard. Keys are prefixed ysl_ and are shown only once at creation — store them securely.

API Plans

API usage is metered per day, resetting at midnight UTC. Plans are independent of website plans.

Subscribe to an API plan →

Rate Limits

Every response includes rate limit headers:

When you exceed your daily limit the API returns 429 Too Many Requests. Limits reset at 00:00:00 UTC each day.

Errors

All errors return a JSON object with an error field:

{
  "error":  "Invalid URL. Must start with http:// or https://",
  "status": 400
}

POST /shorten

Shorten a URL. Returns the short URL, slug, and a QR code URL.

curl -X POST https://yourshortsite.link/api/v1/shorten \
  -H "X-Api-Key: ysl_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url":         "https://example.com/very/long/path?with=params",
    "custom_slug": "my-campaign"
  }'

{
  "shortUrl":  "https://yourshortsite.link/my-campaign",
  "slug":      "my-campaign",
  "url":       "https://example.com/very/long/path?with=params",
  "createdAt": "2025-04-16T12:00:00+00:00",
  "qrUrl":     "https://yourshortsite.link/api/qr.php?slug=my-campaign"
}

POST /utm

Build a UTM-tagged URL and optionally shorten it in one step.

curl -X POST https://yourshortsite.link/api/v1/utm \
  -H "X-Api-Key: ysl_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url":          "https://example.com/landing",
    "utm_source":   "discord",
    "utm_medium":   "social",
    "utm_campaign": "summer_launch",
    "shorten":      true
  }'

{
  "utmUrl":   "https://example.com/landing?utm_source=discord&utm_medium=social&utm_campaign=summer_launch",
  "shortUrl": "https://yourshortsite.link/aB3xY2",
  "slug":     "aB3xY2",
  "qrUrl":    "https://yourshortsite.link/api/qr.php?slug=aB3xY2"
}

GET /links

Retrieve a paginated list of your short links, newest first.

curl "https://yourshortsite.link/api/v1/links?limit=5&offset=0" \
  -H "X-Api-Key: ysl_your_key"

{
  "links": [
    {
      "slug":      "my-campaign",
      "url":       "https://example.com/...",
      "shortUrl":  "https://yourshortsite.link/my-campaign",
      "clicks":    142,
      "createdAt": "2025-04-16T12:00:00+00:00",
      "utmTagged": false,
      "qrUrl":     "https://yourshortsite.link/api/qr.php?slug=my-campaign"
    }
  ],
  "total":  47,
  "limit":  5,
  "offset": 0
}

GET /stats/{slug}

Get detailed stats for a specific short link. Only links belonging to your account can be queried.

curl https://yourshortsite.link/api/v1/stats/my-campaign \
  -H "X-Api-Key: ysl_your_key"

{
  "slug":      "my-campaign",
  "url":       "https://example.com/...",
  "shortUrl":  "https://yourshortsite.link/my-campaign",
  "clicks":    142,
  "createdAt": "2025-04-16T12:00:00+00:00",
  "utmTagged": false
}

GET /qr/{slug}

Returns a QR code PNG image for the given slug. Use directly as an <img src="..."> in your app.

curl "https://yourshortsite.link/api/v1/qr/my-campaign?size=400" \
  -H "X-Api-Key: ysl_your_key" \
  --output qr.png

GET /usage

Check your API usage for today.

curl https://yourshortsite.link/api/v1/usage \
  -H "X-Api-Key: ysl_your_key"

{
  "plan":      "api_business",
  "planLabel": "Business API",
  "used":      87,
  "limit":     250,
  "remaining": 163,
  "resetAt":   "2025-04-17T00:00:00Z",
  "date":      "2025-04-16"
}

Code examples

JavaScript (fetch)

const response = await fetch('https://yourshortsite.link/api/v1/shorten', {
  method:  'POST',
  headers: {
    'X-Api-Key':     'ysl_your_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ url: 'https://example.com/long' }),
});
const data = await response.json();
console.log(data.shortUrl); // https://yourshortsite.link/abc123

Python (requests)

import requests

response = requests.post(
    'https://yourshortsite.link/api/v1/shorten',
    headers={'X-Api-Key': 'ysl_your_key'},
    json={'url': 'https://example.com/long'},
)
data = response.json()
print(data['shortUrl'])

PHP

$ch = curl_init('https://yourshortsite.link/api/v1/shorten');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode(['url' => 'https://example.com/long']),
    CURLOPT_HTTPHEADER     => [
        'X-Api-Key: ysl_your_key',
        'Content-Type: application/json',
    ],
]);
$data = json_decode(curl_exec($ch), true);
echo $data['shortUrl'];