API Documentation
JavaScript / TypeScript SDK
@plung/sdk is the official TypeScript SDK for the Plung API. It works in Node.js and the browser, and it ships as an ESM-only package for modern JavaScript applications.
Installation
bash
pnpm add @plung/sdk
# or
npm install @plung/sdkQuick start
ts
import { PlungClient } from "@plung/sdk"
const client = new PlungClient("your_api_key_here")
const { data, meta } = await client.links.create({
url: "https://example.com/my-very-long-url",
})
console.log(data.shortUrl)
console.log(meta.rateLimit.remaining)POST
/v2/shortenAll PlansCreates a shortened URL with API key authentication. Returns the short URL, the generated short code, and link metadata. Destination URLs are verified against real-time threat intelligence before acceptance.
Requires API key: This endpoint requires authentication via the
Authorization header with a Bearer token. See the Authentication page for details.Request Headers
| Parameter | Type | Required | Plan | Description |
|---|---|---|---|---|
| Authorization | string | Required | All Plans | Your API key as a Bearer token in the Authorization header. Returns a 401 error if missing, invalid, or revoked. |
| Content-Type | string | Required | All Plans | Must be set to "application/json". |
Request Body Parameters
| Parameter | Type | Required | Plan | Description |
|---|---|---|---|---|
| url | string | Required | All Plans | The full destination URL to shorten. Must include http:// or https://. Verified against real-time threat intelligence. |
| alias | string | Optional | Hobby+ | Custom vanity short code (Hobby: min 4 chars, Indie/Pro: min 3 chars, max 50 chars). Alphanumeric and hyphens only. Prohibited keywords return 400. Attempting on Free returns 403 Forbidden. |
| expiresIn | number | Optional | Hobby+ | Link time-to-live in seconds (minimum 60s). The link is automatically purged from edge routing after this interval. Attempting on Free returns 403 Forbidden. |
| maxClicks | number | Optional | Hobby+ | Maximum redirection clicks allowed (minimum 1). Once reached, the link expires and visitors receive an HTTP 410 Gone response. Attempting on Free returns 403 Forbidden. |
| password | string | Optional | Indie+ | Password protection for the short link (4 to 100 characters). Visitors must enter this password on an intermediate page before redirection. Attempting on Free or Hobby returns 403 Forbidden. |
Request Examples
Minimal request (works on all plans including Free):
bash
curl -X POST https://api.plung.co/v2/shorten \
-H "Authorization: Bearer your_api_key_here" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/my-very-long-url"}'Advanced request (Hobby & Indie/Pro plans):
bash
curl -X POST https://api.plung.co/v2/shorten \
-H "Authorization: Bearer your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/my-very-long-url",
"alias": "launch-2026",
"password": "SecurePass123",
"expiresIn": 86400,
"maxClicks": 1000
}'Success Response
Status: 201 Created
json
{
"shortUrl": "https://plu.ng/launch-2026",
"shortCode": "launch-2026",
"url": "https://example.com/my-very-long-url",
"alias": "launch-2026",
"expiresAt": "2026-09-30T14:00:00.000Z",
"maxClicks": 1000,
"createdAt": "2026-09-29T14:00:00.000Z"
}The
alias, expiresAt, and maxClicks fields are only present when the corresponding options were configured in the request.Error Responses
| Status | Cause | Message / Explanation |
|---|---|---|
400 | Invalid or missing URL | "Please provide a valid URL" |
400 | Custom alias taken | "Alias is already taken" |
400 | Reserved alias violation | "This alias is reserved and cannot be used" |
400 | Threat protection block | "URL appears to be unsafe and cannot be shortened" |
401 | Missing / Invalid API key | "API key required. Pass your key as: Authorization: Bearer <key>" |
403 | Feature not available on plan | "Your current plan does not include this feature." (e.g. sending alias/expiration on Free, or password on Hobby) |
429 | Rate limit / Quota exceeded | "Rate limit exceeded. Try again in the next minute." / "Monthly link limit reached." |
503 | Maintenance mode active | "Service is temporarily unavailable for maintenance" |
Plan-Gating Error Example (403 Forbidden):
json
{
"statusCode": 403,
"timestamp": "2026-09-29T13:37:26.422Z",
"path": "/v2/shorten",
"method": "POST",
"message": "Your current plan does not include this feature."
}