POST /v2/shorten - API Documentation

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/sdk

Quick start

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)

View on npm

POST/v2/shorten

Creates a shortened URL with API key authentication. Returns the short URL, the generated short code, and metadata about the created link. The destination URL is validated against Google Safe Browsing before acceptance.

Requires API key: This endpoint requires authentication via the Authorization header with a Bearer token. See the Authentication page for details.

Behavior equivalence: This endpoint preserves the legacy shorten behavior, but requires authentication and provides higher per-key rate limits (1000 req/60s vs 5 req/60s).

Request Headers

Parameter	Type	Required	Description
Authorization	string	Required	Your API key as a Bearer token in the Authorization header. Returns a 401 error if missing, invalid, or revoked.
Content-Type	string	Required	Must be set to "application/json".

Request Body Parameters

Parameter	Type	Required	Description
url	string	Required	The full URL to shorten. Must include the protocol (http:// or https://). Returns a 400 error with "Please provide a valid URL" if missing or malformed.
alias	string	Optional	A custom short code (3 to 50 characters). Reserved aliases (system routes, brands, government entities, and malicious patterns) are prohibited unless an override exists. Returns a 400 error if the code is in use, reserved, or if the feature is disabled.
password	string	Optional	A password (4 to 100 characters) that visitors must enter before being redirected. Returns a 400 error with "Password protection is currently disabled on this platform" if the feature is turned off.
expiresIn	number	Optional	Expiration in seconds (minimum 60). The link is automatically deleted after this many seconds.
maxClicks	number	Optional	Maximum number of redirects allowed (minimum 1). Once the count is reached, the link is deleted and subsequent visits receive a 410 Gone response.

Request Examples

Minimal request (required fields only):

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"}'

Full request with all optional parameters:

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": "my-link",
    "password": "SecurePass123",
    "expiresIn": 3600,
    "maxClicks": 500
  }'

Success Response

Status: 201 Created

json

{
  "shortUrl": "https://plung.co/abc12345",
  "shortCode": "abc12345",
  "url": "https://example.com/my-very-long-url",
  "alias": "my-link",
  "expiresAt": "2026-03-07T02:30:00.000Z",
  "maxClicks": 500,
  "createdAt": "2026-02-28T02:30:00.000Z"
}

The alias, expiresAt, and maxClicks fields are only present when the corresponding options were set in the request. If no alias, expiration, or click limit was specified, these fields are omitted from the response.

Error Responses

Status	Cause	Message
`400`	Invalid or missing URL	"Please provide a valid URL"
`400`	Custom alias already taken	"Alias is already taken"
`400`	Reserved alias	"This alias is reserved and cannot be used"
`400`	Alias length out of range	"Alias must be between 3 and 50 characters"
`400`	Password too short or too long	"Password must be between 4 and 100 characters"
`400`	Invalid expiration value	"expiresIn must be at least 60 seconds (1 minute)"
`400`	URL flagged by Safe Browsing	"URL appears to be unsafe and cannot be shortened"
`400`	Feature disabled by platform	"URL shortening is currently disabled" / "Custom aliases are currently disabled on this platform" / "Password protection is currently disabled on this platform" / "URL expiration is currently disabled on this platform"
`401`	Missing API key	"API key required. Pass your key as: Authorization: Bearer <your-key>"
`401`	Invalid or inactive API key	"Invalid or inactive API key."
`429`	Rate limit exceeded	"Rate limit exceeded. Try again in the next minute."
`503`	Maintenance mode active	"Service is temporarily unavailable for maintenance"

PreviousRequest & Response Format NextPOST /v2/shorten/batch