API Documentation
Authentication
Plung uses API key authentication for all developer API access.
v2 API: API Key Authentication
The v2 API requires authentication via API keys. Each request must include an Authorization header with a Bearer token containing your API key. Rate limits are enforced per API key and depend on plan: 60 to 5,000 requests per 60 seconds per key.
API keys are available on all plans, including the free FREE tier. You can manage your API keys and upgrade your plan in the Developer Console. Different pricing tiers offer higher rate limits and monthly request volumes.
| Plan | Rate Limit | Monthly API Calls |
|---|---|---|
| FREE | 60/min | 2,000 |
| HOBBY | 300/min | 25,000 |
| INDIE | 1,000/min | 150,000 |
| PRO | 5,000/min | 500,000 |
Using API Keys
Include your API key as a Bearer token in the Authorization header with every v2 API request:
bash
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"}'Authentication Errors
v2 endpoints return 401 Unauthorized when authentication fails. The response includes a specific error message:
Missing API key:
json
{
"statusCode": 401,
"message": "API key required. Pass your key as: Authorization: Bearer <your-key>",
"error": "Unauthorized"
}Invalid API key:
json
{
"statusCode": 401,
"message": "Invalid or inactive API key.",
"error": "Unauthorized"
}Rate limit exceeded:
json
{
"statusCode": 429,
"message": "Rate limit exceeded. Try again in the next minute."
}Rate Limiting
All v2 API responses include rate limit headers that indicate your current usage:
| Parameter | Type | Required | Description |
|---|---|---|---|
| X-RateLimit-Limit | number | Required | Maximum number of requests allowed per 60-second window for your plan (60 FREE, 300 HOBBY, 1,000 INDIE, 5,000 PRO). |
| X-RateLimit-Remaining | number | Required | Number of requests remaining in the current 60-second window. |
| X-RateLimit-Reset | number | Required | Unix timestamp (seconds) when the rate limit window resets. |
| X-API-Key-Name | string | Required | Human-readable name of the API key used for the request. |
When you exceed the rate limit, the API returns a 429 Too Many Requests response:
json
{
"statusCode": 429,
"message": "Rate limit exceeded. Try again in the next minute."
}For detailed rate limit information, see the Rate Limiting section.