Simple URL Shortener

API Documentation

Simple JSON API to create short links with permanent 301, optional interstitial, and PNG QR codes.

API Overview

Base URL: https://pth.bz

Endpoint

POST https://pth.bz/api/shorten

Content-Type: application/json

Request

Body JSON:

{
  "url": "https://example.com/landing?utm_source=newsletter"
}

Response

200 OK:

{
  "short_url_301": "https://pth.bz/AbC1234",
  "short_url_js": "https://pth.bz/i/AbC1234",
  "qr_301_png_url": "https://pth.bz/?qr=AbC1234",
  "qr_js_png_url": "https://pth.bz/?qi=AbC1234"
}
Other statuses
  • 400 Bad Request — invalid JSON, missing url, or invalid URL.
  • 405 Method Not Allowed — use POST.
  • 429 Too Many Requests — rate limit exceeded.
  • 500 Internal error — transient server error.

Choosing the right redirect

301 (default)

Fast permanent redirect: /CODE

Best for SEO migrations, ads, emails, printed materials.

Interstitial (anti-bot)

Short JS step and referrer is hidden: /i/CODE

Use when bots aggressively follow links or when hiding referrer matters.

QR codes (PNG)

  • For 301: /?qr=CODE
  • For interstitial: /?qi=CODE
  • Optional size in px: &px=640 (200–2048)
<img src="https://pth.bz/?qr=AbC1234&px=640" alt="QR" />

Error responses

{
  "error": "Too many requests"
}

Limits and rules

  • Rate limit: 30 requests per 10 minutes per IP (HTTP 429 on exceed).
  • Only http:// and https:// links are allowed.
  • Max URL length: 2000 characters.
  • JSON only: set Content-Type: application/json.

Examples

curl
curl -X POST "https://pth.bz/api/shorten" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'
JavaScript (fetch)
const res = await fetch('https://pth.bz/api/shorten', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ url: 'https://example.com' })
});
const data = await res.json();
console.log(data.short_url_301, data.short_url_js);
Python (requests)
import requests

r = requests.post('https://pth.bz/api/shorten', json={'url': 'https://example.com'})
print(r.status_code, r.json())

SDKs

Client libraries are planned:

  • Python
  • WordPress
  • npm (JavaScript/TypeScript)
  • Go