POST /v2/shorten/batch - API Documentation

API Documentation

POST/v2/shorten/batch

Creates multiple shortened URLs in a single request with API key authentication. Accepts an array of up to 50 URLs. Returns a 200 OK array of results for both successes and failures within the batch.

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 batch-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 Schema

The root request body must contain a single urls array. If the array is empty or contains more than 50 items, a 400 Bad Request is returned.

Parameter	Type	Required	Description
urls	array	Required	An array of URL objects to be shortened (minimum 1, maximum 50 items).

Array Item Schema

Each object in the urls array represents a single link to shorten.

Parameter	Type	Required	Description
url	string	Required	The full URL to shorten. Must include the protocol (http:// or https://).
alias	string	Optional	A custom short code (3 to 50 characters, alphanumeric and hyphens only).
password	string	Optional	A password (4 to 100 characters) that visitors must enter before being redirected.
expiresIn	number	Optional	Time-to-live in seconds (minimum 60). The link is automatically deleted after this many seconds.
maxClicks	number	Optional	Maximum number of redirects allowed before the link expires.

Request Examples

Batch of 3 URLs with a mix of configurations:

bash

curl -X POST https://api.plung.co/v2/shorten/batch \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      {
        "url": "https://example.com/first-link"
      },
      {
        "url": "https://example.com/newsletter",
        "alias": "my-newsletter"
      },
      {
        "url": "https://example.com/secret",
        "password": "secure-password",
        "expiresIn": 86400,
        "maxClicks": 100
      }
    ]
  }'

Success Response (Partial Failures Handled)

Status: 200 OK

Important: A batch request always returns a 200 OK unless the root payload is malformed. If individual items fail validation (e.g., alias already taken), they will appear in the results array with "success": false.

json

{
  "results": [
    {
      "index": 0,
      "success": true,
      "shortUrl": "https://plung.co/abc12345",
      "shortCode": "abc12345",
      "url": "https://example.com/first-link"
    },
    {
      "index": 1,
      "success": false,
      "error": "Alias is already taken"
    },
    {
      "index": 2,
      "success": true,
      "shortUrl": "https://plung.co/xyz9876",
      "shortCode": "xyz9876",
      "url": "https://example.com/secret",
      "expiresAt": "2026-03-08T02:30:00.000Z",
      "maxClicks": 100
    }
  ]
}

Error Responses

Status	Cause	Message
`400`	Array bounds exceeded	"The urls array cannot exceed 50 items" or "The urls array must contain at least 1 item"
`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"

PreviousPOST /v2/shorten NextGET /v2/qr/:shortCode