Introducing Plung API v2: Authenticated Endpoints and API Keys

We shipped Plung API v1 to provide fast, zero-auth link shortening. The v1 IP-based limits (10 req/minute global, 5 req/minute for shortening) work for individual developers, but they break down in production environments.

When your infrastructure sits behind a NAT gateway or load balancer, every request shares the same outbound IP and competes for a single rate limit bucket. Without API keys, we had no reliable way to identify traffic, offer higher limits, or build isolated client dashboards.

Today we are releasing Plung API v2 to solve this. This update provides API key authentication and per-key rate limiting. The v1 API remains fully functional and untouched.

What Shipped

API Keys. Request a v2 API key via our support channels. Each key is scoped to your account and provides a stable identity for tracking usage. We are currently building a complete user dashboard for self-serve key management, but for now, reach out to support to get your key generated or revoked.

Per-Key Rate Limits. Authenticated v2 requests are granted 1000 requests per 60 seconds per key. This scales linearly with your actual application usage, bypassing IP-based restrictions.

v2 Endpoints. We added authenticated versions of all core endpoints:

• POST /v2/shorten
• POST /v2/shorten/batch
• GET /v2/qr/:shortCode
• GET /v2/stats/:shortCode

To use them, pass your key via the Authorization: Bearer ... header. The current request and response schemas follow the normalized /v2 contract.

Rate Limit Headers. All v2 responses include headers detailing your quota usage:

• X-RateLimit-Limit: Maximum requests per window (1000).
• X-RateLimit-Remaining: Requests left in the current window.
• X-RateLimit-Reset: Unix timestamp when the limit resets.
• X-API-Key-Name: The registered name of the key used.

If you hit the limit, you get a 429 Too Many Requests response. Check X-RateLimit-Reset to determine when to retry.

Example Request

v2 (Key Authenticated):

curl -X POST https://api.plung.co/v2/shorten \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key_here" \
  -d '{"url": "https://example.com"}'

Migration

If v1 limits work for you, do nothing. If you need higher throughput:

1. Request a v2 API key via our support channels.
2. Use the /v2/ endpoint paths.
3. Attach the Authorization: Bearer ... header.
4. Read the rate limit headers to monitor capacity.

Documentation for the v2 endpoints is live. Both v1 and v2 APIs run in parallel.