REST API v1

Developer API Documentation

Automate link shortening, generate dynamic QR codes, and retrieve real-time click telemetry using the TappyURL REST API.

Create Free Account View API Plans
API Status: Operational
Base Endpoint:
https://tappyurl.com/api/v1
Getting Started
Endpoints

Overview

The TappyURL API is organized around REST. All requests must be made over HTTPS and will return JSON formatted responses.

Production Base URL:
https://tappyurl.com/api/v1

Authentication

To authenticate API requests, include your API Key in the X-API-Key request header or as a Bearer token in the Authorization header.

API access is included with Standard ($9/mo), Pro ($29/mo), and Premium plans.
Header Authentication Example:
X-API-Key: tap_live_9a8b7c6d5e4f3g2h1i0j...
Content-Type: application/json
Accept: application/json

Rate Limits & Quotas

Plan Price Short Links QR Codes API Access Rate Limit
Guest (No Sign) Free 1 Link 1 QR —
Free (Sign-in) $0 5 Links / mo 5 QR / mo —
Standard $9 / mo 500 Links / mo 100 QR / mo Yes 1,000 req/hr
Pro $29 / mo 2,500 Links / mo 500 QR / mo Yes 5,000 req/hr
Premium $49 / mo 10,000 Links / mo 2,000 QR / mo Yes 20,000 req/hr

HTTP Status Codes

  • 200 OK - Request completed successfully.
  • 201 Created - Short link or resource created successfully.
  • 400 Bad Request - Validation error or malformed request body.
  • 401 Unauthorized - Invalid or missing API Key.
  • 403 Forbidden - Plan upgrade required (Free plan) or quota exceeded.
  • 429 Too Many Requests - Hourly or daily rate limit exceeded.
POST

/api/v1/shorten

Create a new shortened link with optional custom alias, password protection, and UTM campaign parameters.

Request Body Parameters
Field Type Required Description
destination_url string Required The target URL to shorten (must include http:// or https://)
title string Optional Human-readable title for the link
custom_alias string Optional Custom short code slug (e.g. my-campaign)
password string Optional Password to protect the redirection target
expires_at string Optional ISO-8601 or Y-m-d H:i:s expiration date
utm_source string Optional UTM source tag (e.g. newsletter) 
curl -X POST "https://tappyurl.com/api/v1/shorten" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "destination_url": "https://example.com/long-article",
    "title": "Summer Campaign",
    "custom_alias": "summer-promo"
  }'
const response = await fetch("https://tappyurl.com/api/v1/shorten", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  body: JSON.stringify({
    destination_url: "https://example.com/long-article",
    title: "Summer Campaign",
    custom_alias: "summer-promo"
  })
});
const data = await response.json();
console.log(data.data.short_url);
$client = new \GuzzleHttp\Client();
$response = $client->post('https://tappyurl.com/api/v1/shorten', [
    'headers' => [
        'X-API-Key' => 'YOUR_API_KEY',
        'Accept'    => 'application/json',
    ],
    'json' => [
        'destination_url' => 'https://example.com/long-article',
        'title'           => 'Summer Campaign',
        'custom_alias'    => 'summer-promo',
    ],
]);
$data = json_decode($response->getBody(), true);
import requests

url = "https://tappyurl.com/api/v1/shorten"
headers = {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
    "Accept": "application/json"
}
payload = {
    "destination_url": "https://example.com/long-article",
    "title": "Summer Campaign",
    "custom_alias": "summer-promo"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
Example Response (201 Created)
{
  "success": true,
  "message": "Short URL created successfully.",
  "data": {
    "id": 142,
    "short_code": "summer-promo",
    "custom_alias": "summer-promo",
    "short_url": "https://tappyurl.com/summer-promo",
    "original_url": "https://example.com/long-article",
    "title": "Summer Campaign",
    "click_count": 0,
    "unique_click_count": 0,
    "is_active": true,
    "is_password_protected": false,
    "has_qr_code": false,
    "expires_at": null,
    "created_at": "2026-09-12T00:00:00Z"
  }
}
GET

/api/v1/urls

Retrieve paginated list of all shortened URLs created by the authenticated account.

Example Request
curl -X GET "https://tappyurl.com/api/v1/urls?per_page=10" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"
POST

/api/v1/qr-codes

Generate dynamic high-resolution QR codes in SVG or PNG formats with custom colors and sizes.

Example Request
curl -X POST "https://tappyurl.com/api/v1/qr-codes" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "https://tappyurl.com/summer-promo",
    "size": 350,
    "format": "svg",
    "color": "#0d6efd"
  }'
GET

/api/v1/analytics/{code}

Retrieve detailed click breakdown, top visitor countries (GeoIP), device types, browsers, and referrer domains.

Example Request
curl -X GET "https://tappyurl.com/api/v1/analytics/summer-promo?days=30" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"
GET

/api/v1/account

Check current subscription tier, quota limits, and monthly link/QR code usage.

Example Request
curl -X GET "https://tappyurl.com/api/v1/account" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"