Plinkly API Documentation

Quickstart

The fastest way to integrate Plinkly into your application. All you need is your API token.

Base URL

https://plink.ly/apiv

Auth Header

Authorization: Bearer <token>

Content-Type

application/json

1. Create a Short Link

BASH (cURL)

curl -X POST "https://plink.ly/apiv/shorten" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/my-long-page",
    "slug": "custom-alias",
    "utm_source": "newsletter",
    "ad_enabled": 1
  }'

Authentication

Authenticate your requests by including your secret API token in the Authorization header. You can generate or manage your tokens from your Dashboard Settings.

HTTP Header

Authorization: Bearer 0123456789abcdef0123456789abcdef...

Errors & Limits

Our API uses standard HTTP status codes. Failed requests will always return a JSON response containing an error message.

400 Bad Request: Invalid parameters or malformed JSON.
401 / 403 Unauthorized: Missing token, or feature locked (e.g. Password Protection on a Free Plan).
429 Too Many Requests: Rate limit (20 req/min) or plan's creation limits reached.

POST /shorten

Create a new shortened link with advanced configurations.

url (required): The destination URL.
slug (optional): Custom alias (e.g. 'summer-sale').
domain_id (optional): ID of your custom domain.
expire_days (optional): Days until link expires (0 = forever).
max_clicks (optional): Limit total clicks allowed.
password (optional): Protect link with a password.
utm_source, utm_medium, utm_campaign_id, utm_note (optional): UTM tagging.
geo_routes (optional): JSON object for country-based routing.
ab_test_data (optional): JSON object for A/B testing splits.
ad_enabled (optional): Enable or disable custom ads (1 or 0).

GET /get_links

Retrieve a paginated list of all your shortened links.

page (optional): The page number (default: 1).
limit (optional): Items per page, max 100 (default: 15).

BASH

curl "https://plink.ly/apiv/get_links?page=1&limit=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

PUT /update

Dynamically update an existing short link. Provide only the fields you wish to change.

Query: ?slug=target-alias

BASH

curl -X PUT "https://plink.ly/apiv/update?slug=old-alias" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "new_slug": "new-alias",
    "password": "secretPassword123",
    "utm_source": "twitter"
  }'

DELETE /delete

Permanently remove a short link and its click data.

BASH

curl -X DELETE "https://plink.ly/apiv/delete?slug=abc12" \
  -H "Authorization: Bearer YOUR_TOKEN"

GET /stats

Retrieve advanced analytics for a specific link. Returns daily clicks, top countries, and top referrers.

slug (required): The link alias.
from (optional): Start date YYYY-MM-DD.
to (optional): End date YYYY-MM-DD.

BASH

curl "https://plink.ly/apiv/stats?slug=abc12&from=2026-01-01&to=2026-03-21" \
  -H "Authorization: Bearer YOUR_TOKEN"

GET /me

Fetch your current profile details, subscription plan limits, and real-time usage metrics.

BASH

curl "https://plink.ly/apiv/me" \
  -H "Authorization: Bearer YOUR_TOKEN"

GET /get_domains

Retrieve a list of verified custom domains on your account to use their id when creating links.

BASH

curl "https://plink.ly/apiv/get_domains" \
  -H "Authorization: Bearer YOUR_TOKEN"

Integrations (Signed Requests)

For server-to-server communication, we use HMAC signatures instead of Bearer tokens for enhanced security.

Pseudo Code

signature = HMAC_SHA256(secret, timestamp + rawJSONBody)

// Headers to send:
X-PLINKLY-TIMESTAMP: {timestamp}
X-PLINKLY-SIGNATURE: {signature}