API Documentation

Complete REST API reference for integrating with Zipdup.link

Version 1.0

Introduction

Welcome to the Zipdup.link API! Our REST API allows you to programmatically shorten URLs, manage your links, and access analytics data.

Base URL

https://zipdup.link/api

Authentication

API Key Authentication

Include your API key in the request headers:

X-API-Key: your_api_key_here

Never expose your API key in client-side code or public repositories.

Rate Limits

All API endpoints enforce rate limiting based on your subscription plan. Rate limits are tracked per API key or session.

API Access by Plan

Plan	API Shortening	Status
FREE	No Access	Requires Upgrade
BASIC	No Access	Requires Upgrade
STANDARD	60 requests/minute	Full Access
PREMIUM	300 requests/minute	Full Access

💡 Note: FREE and BASIC plans do not have API access. Upgrade to STANDARD or PREMIUM to use the API.

Other Endpoint Limits

• QR Code (Anonymous): 20 requests/minute
• QR Code (Authenticated): 100 requests/minute
• API Key Operations: 5 requests/minute
• Authentication: 5 attempts per 5 minutes

Rate Limit Headers

All API responses include rate limit information in the headers:

X-RateLimit-Limit: 60            # Max requests allowed
X-RateLimit-Remaining: 57        # Requests remaining
X-RateLimit-Reset: 2025-10-31... # Reset timestamp
X-RateLimit-Source: redis        # Limiter source
Retry-After: 42                  # Seconds until retry (when limited)

When rate limited, the API returns 429 Too Many Requests with a Retry-After header indicating seconds until you can retry.

POST /api/shorten

Create Short Link

Creates a new shortened URL.

Parameter	Type	Required	Description
url	string	Required	The URL to shorten
customCode	string	Optional	Custom short code (3-50 characters, alphanumeric + dash/underscore). Requires BASIC plan or higher.
domain	string	Optional	Domain selection: 'zipdup.link' (all plans), 'zipd.cc' or 'zdup.link' (STANDARD/PREMIUM only). Defaults to 'zipdup.link'.

curl -X POST https://zipdup.link/api/shorten \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/very/long/url",
    "customCode": "my-link",
    "domain": "zipd.cc"
  }'

GET /api/links

List Links

Retrieves a paginated list of your shortened links.

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number (min: 1)
limit	integer	10	Items per page (max: 50)
sortBy	string	createdAt	Sort field
sortOrder	string	desc	Sort order: asc or desc
search	string	-	Search term

curl -X GET https://zipdup.link/api/links?page=1&limit=10 \
  -H "X-API-Key: your_api_key_here"

GET /api/links/{id}

Get Link Details

Retrieves details for a specific link.

Path Parameters

Parameter	Type	Description
id	string	Link ID or address

curl -X GET https://zipdup.link/api/links/my-link \
  -H "X-API-Key: your_api_key_here"

PATCH /api/links/{id}

Update Link

Updates a link's target URL.

Request Body

Parameter	Type	Description
target	string	New target URL

curl -X PATCH https://zipdup.link/api/links/my-link \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "https://example.com/new/target/url"
  }'

DELETE /api/links/{id}

Delete Link

Permanently deletes a link.

curl -X DELETE https://zipdup.link/api/links/my-link \
  -H "X-API-Key: your_api_key_here"

GET /api/keys

List API Keys

Retrieves a list of your API keys.

curl -X GET https://zipdup.link/api/keys \
  -H "X-API-Key: your_api_key_here"

POST /api/keys

Create API Key

Creates a new API key.

Parameter	Type	Required	Description
name	string	Required	Descriptive name for the API key

curl -X POST https://zipdup.link/api/keys \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API"
  }'

Important: Save the full API key when generated. It won't be shown again for security reasons.

DELETE /api/keys/{id}

Delete API Key

Permanently deletes an API key. This action cannot be undone.

Path Parameters

Parameter	Type	Description
id	string	API Key ID (UUID)

curl -X DELETE https://zipdup.link/api/keys/123e4567-e89b-12d3-a456-426614174000 \
  -H "X-API-Key: your_api_key_here"

Success Response (200)

{
  "message": "API key deleted successfully"
}

QR Code Generation

Generate QR codes for shortened URLs. Supports multiple formats (SVG, PNG, JPEG, WebP) with customization options.

GET /api/qrcode

Simple QR Code Generation

Generate a QR code image with basic options via query parameters. No authentication required.

Parameter	Type	Default	Description
code	string	Required	Short code for the link
format	string	svg	svg, png, jpeg, or webp
size	integer	256	Size in pixels (100-1000)

curl "https://zipdup.link/api/qrcode?code=my-link&format=png&size=512" -o qrcode.png

Rate Limits: 20 requests/minute (anonymous), 100 requests/minute (authenticated)

POST /api/qrcode

Advanced QR Code Generation

Generate QR codes with advanced customization options including colors, error correction, and margins.

Parameter	Type	Default	Description
shortCode	string	-	Short code (required if no url)
url	string	-	Custom URL (required if no shortCode)
format	string	svg	svg, png, jpeg, or webp
size	integer	256	Size in pixels (100-1000)
margin	integer	4	Quiet zone margin
errorCorrectionLevel	string	M	L (7%), M (15%), Q (25%), H (30%)
darkColor	string	#000000	Dark color (hex)
lightColor	string	#FFFFFF	Light color (hex)
download	boolean	false	Return as downloadable file

curl -X POST https://zipdup.link/api/qrcode \
  -H "Content-Type: application/json" \
  -d '{
    "shortCode": "my-link",
    "format": "png",
    "size": 512,
    "errorCorrectionLevel": "H",
    "darkColor": "#1a56db",
    "lightColor": "#ffffff"
  }'

Success Response (200)

{
  "success": true,
  "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "format": "png",
  "url": "https://zipdup.link/my-link"
}

Error Codes

Status Code	Description	Example Response
200	Success	Request completed successfully
400	Bad Request	{"error": "Invalid URL format"}
401	Unauthorized	{"error": "Invalid API key"}
403	Forbidden	{"error": "API access requires Standard or Premium plan"}
404	Not Found	{"error": "Link not found"}
429	Rate Limit Exceeded	{"error": "Too Many Requests", "retryAfter": 42}
500	Server Error	{"error": "Internal server error"}

Code Examples

JavaScript/Node.js

const response = await fetch('https://zipdup.link/api/shorten', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://example.com/very/long/url',
    customCode: 'my-link',
    domain: 'zipd.cc'  // Optional: zipdup.link, zipd.cc, or zdup.link
  })
});

const data = await response.json();
console.log(data.shortUrl); // https://zipd.cc/my-link

Python

import requests

url = 'https://zipdup.link/api/shorten'
headers = {
    'X-API-Key': 'your_api_key_here',
    'Content-Type': 'application/json'
}
data = {
    'url': 'https://example.com/very/long/url',
    'customCode': 'my-link',
    'domain': 'zipd.cc'  # Optional: zipdup.link, zipd.cc, or zdup.link
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result['shortUrl'])  # https://zipd.cc/my-link

cURL

curl -X POST https://zipdup.link/api/shorten \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/very/long/url",
    "customCode": "my-link",
    "domain": "zipd.cc"
  }'