REST API Reference • Version 1.0

Developer API Documentation

Seamlessly connect your systems, automations (Zapier, Make, n8n), CRMs, or mobile apps to shorten URLs, generate branded QR codes, and retrieve detailed analytics.

Download Postman Collection Get API Key
Base URL: https://zqrl.link/api/v1

Authentication

All requests to the API must include your secret API key in the Authorization HTTP header as a Bearer token.

Authorization: Bearer <YOUR_API_KEY>
Accept: application/json
GET /api/v1/me
Profile & Quota

Retrieve the authenticated user profile, active subscription plan, and link creation quota consumption for the current month. 

{
  "status": "success",
  "data": {
    "id": 1,
    "name": "Alex Doe",
    "email": "alex@example.com",
    "plan": {
      "name": "Pro Monthly",
      "type": "recurring",
      "api_access": true,
      "shorturl_limit_per_month": 500
    },
    "usage": {
      "links_created_this_month": 34,
      "links_remaining_this_month": 466,
      "total_links": 128,
      "total_visits": 4209
    }
  }
}
POST /api/v1/urls
Create Short URL

Create a shortened link and automatically generate its QR code. Custom slug aliases, password protection, and custom domains can optionally be provided.

Field Type Required Description
destination_url string (url) Yes The destination target URL (e.g. https://yoursite.com/campaign)
title string Optional Friendly name or title for your link dashboard
alias string Optional Custom slug key (e.g. "summer-sale"). Must be unique.
domain_id integer Optional ID of a verified custom domain. Omit for default domain.
password string Optional Password required to visit the short URL
single_use boolean Optional Set to true to disable the link immediately after 1 visit
# Request
curl -X POST "https://zqrl.link/api/v1/urls" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"destination_url": "https://example.com/promo", "title": "Summer Campaign", "alias": "summer-deals"}'

# Response (201 Created) 
{
  "status": "success",
  "message": "Short URL created successfully.",
  "data": {
    "id": 42,
    "title": "Summer Campaign",
    "url_key": "summer-deals",
    "short_url": "https://zqrl.link/s/summer-deals",
    "destination_url": "https://example.com/promo",
    "is_single_use": false,
    "is_active": true,
    "is_expired": false,
    "visits_count": 0,
    "created_at": "2026-09-03T17:15:00+00:00"
  }
}
GET /api/v1/urls
List Links

Retrieve a paginated list of your shortened links. Supports filtering by status (active, inactive) and search keyword.

# Example Query:
curl -X GET "https://zqrl.link/api/v1/urls?per_page=15&status=active&search=campaign" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Manage Specific Link

GET /api/v1/urls/{id_or_key}

Retrieve link details by either its numeric ID or its URL key alias.

PUT /api/v1/urls/{id_or_key}

Update destination URL, title, password, or expiration/activation status. All fields are optional; only the provided fields will be updated.

Field Type Description
destination_url string (url) The new destination target URL
title string Friendly name or title for your link dashboard
password string New password to protect the short URL
status string Set to active or inactive to instantly toggle link access.
deactivated_at string | null Set a future ISO-8601 date to schedule expiration. Set to null to remove expiration.
single_use boolean Set to true to disable the link immediately after 1 visit.
DELETE /api/v1/urls/{id_or_key}

Permanently delete a short URL and all its associated click logs.

GET /api/v1/urls/{id_or_key}/qr-code

Returns customized or standard QR code for an existing Short URL. Supports optional query parameters: foreground_color, background_color, module_style (square, dots, round), eye_style (square, circle, pointy), size, margin, and format (png, svg, base64).

Analytics & Visit Tracking

GET /api/v1/urls/{id_or_key}/analytics

Fetches aggregated click metrics: total visits, unique visitors, countries breakdown, operating systems, browsers, and daily visit timeline.

{
  "status": "success",
  "data": {
    "metrics": {
      "total_visits": 1540,
      "unique_visitors": 1280,
      "today_visits": 42,
      "last_7_days_visits": 310
    },
    "countries": [
      {"country": "United States", "country_code": "US", "visits": 850},
      {"country": "India", "country_code": "IN", "visits": 340}
    ],
    "operating_systems": [
      {"os": "iOS", "visits": 620},
      {"os": "Android", "visits": 480},
      {"os": "Windows", "visits": 300}
    ]
  }
}
GET /api/v1/domains
Custom Domains

Returns all verified custom domains configured for your account, as well as the default domain. Use the domain id when creating short URLs.

HTTP Status Codes & Errors

Code Status Meaning
200 OK Request completed successfully.
201 Created Resource successfully created.
401 Unauthorized Missing, invalid, or revoked API Bearer token.
403 Forbidden API access is not included in current subscription plan, or account deactivated.
404 Not Found The requested link or resource was not found.
422 Unprocessable Entity Validation error (e.g. invalid URL, duplicate slug, monthly link limit reached).