API Rate Limits

Spoo.me API implements rate limiting to ensure fair usage and maintain service quality for all users. Rate limits vary based on authentication method and API version.

API v1 Rate Limits (Recommended)

The new v1 API offers significantly higher rate limits with authentication:

With Authentication (JWT or API Key)

Per Minute

60 requests

Per Day

5,000 requests

Endpoints

All v1 endpoints

Without Authentication (Anonymous)

Per Minute

20 requests

Per Day

200 requests

Endpoints

Limited endpoints

Get far higher limits by using API keys or JWT authentication: 60 vs 20 requests per minute, and 5,000 vs 200 requests per day.

API v0 Rate Limits (Legacy)

The legacy v0 API has lower rate limits:

Per Minute

5 short URLs per IP

Per Day

50 short URLs per IP

The v0 API is legacy, does not support authentication, and is strictly rate limited. Migrate to the v1 API for dramatically higher limits and features. Rate-limited responses from the legacy shorten endpoints carry an X-Spoo-Hint header (and a hint field on JSON responses) with the migration path.

Rate Limits by Endpoint

URL Shortening

v1 API Endpoints

Endpoint	Authenticated	Anonymous	Notes
`POST /api/v1/shorten`	60/min, 5000/day	20/min, 200/day	v1 API

v0 API Endpoints (Legacy)

The following endpoints are part of the legacy v0 API. They do not support authentication and have lower rate limits.

Endpoint	Authenticated	Anonymous	Notes
`POST /`	-	5/min, 50/day	v0 API (legacy)
`POST /emoji`	-	5/min, 50/day	v0 API (legacy)

URL Management

Endpoint	Authenticated	Anonymous	Notes
`GET /api/v1/urls`	60/min, 5000/day	Not allowed	Requires auth
`PATCH /api/v1/urls/{id}`	60/min, 5000/day	Not allowed	Requires auth
`PATCH /api/v1/urls/{id}/status`	60/min, 5000/day	Not allowed	Requires auth
`DELETE /api/v1/urls/{id}`	60/min, 5000/day	Not allowed	Requires auth

Analytics

Endpoint	Authenticated	Anonymous	Notes
`GET /api/v1/stats`	60/min, 5000/day	Not allowed	Requires auth
`GET /api/v1/stats/links/{url_id}`	60/min, 5000/day	Not allowed	Requires auth
`GET /api/v1/export`	30/min, 1000/day	Not allowed	Requires auth
`GET /api/v1/export/links/{url_id}`	30/min, 1000/day	Not allowed	Requires auth
`GET/POST /api/v1/public/stats/{short_code}`	60/min, 2000/day	20/min, 500/day	Auth optional
`POST /stats/{code}`	-	20/min, 1000/day	v0 API (legacy)
`POST /export/{code}/{format}`	-	10/min, 200/day	v0 API (legacy)

Authentication & Rate Limits

How you authenticate directly affects your rate limits:

API Key Authentication (Recommended)

Rate Limits: 60/min, 5000/dayBenefits:

Far higher rate limits than anonymous
Access to URL management endpoints
Full analytics and export for all your links
Long-lived tokens for automation

How to use: Create an API key and include it in the Authorization header:

Authorization: Bearer spoo_YOUR_API_KEY

JWT Token Authentication

Rate Limits: 60/min, 5000/dayBenefits:

Same rate limits as API keys
Full dashboard access
Can create/manage API keys
Manage URLs via web UI

How to use: Obtain JWT via OAuth/login and include in header:

Authorization: Bearer YOUR_JWT_TOKEN

Anonymous (No Authentication)

Rate Limits: 20/min, 200/day (public per-link stats: 20/min, 500/day)Limitations:

Far lower rate limits
Cannot manage URLs later
Stats limited to the public per-link endpoint (links with private stats appear as 404)
Cannot use URL management endpoints

How to use: Simply make requests without authentication header.

Rate Limit Headers

When you make requests to rate-limited endpoints, the response will include headers indicating your current usage:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640995200

Most endpoints enforce a per-minute and a per-day window at once; the headers describe the shortest window. 429 responses additionally carry a Retry-After header.

Handling Rate Limits

When you exceed the rate limit, you’ll receive a 429 Too Many Requests response:

{
  "error": "Too many requests",
  "code": "rate_limit_exceeded",
  "hint": "Anonymous requests get the lowest limits. Authenticate with a free account or an API key for 60 per minute and 5000 per day."
}

The hint names the tier with higher limits. It appears on anonymous v1 requests and the legacy mint endpoints (POST /, POST /emoji), and is also sent as an X-Spoo-Hint response header so it reaches callers that receive the HTML error page or ignore the body.

Need Higher Limits?

If you need higher rate limits for your application:

Contact Support

If you still need higher limits, contact our support team at support@spoo.me with:

Details about your use case
Expected request volume
Description of your application

Next Steps

Create API Keys

Get started with API key authentication

API Reference

Explore all available endpoints

Quick Start

Build your first integration

Python Library

Use our official SDK

Getting Started

API v1 Reference

API v0 Reference (Legacy)

Tools & Libraries

Self Hosting

API v1 Rate Limits (Recommended)

With Authentication (JWT or API Key)

Per Minute

Per Day

Endpoints

Without Authentication (Anonymous)

Per Minute

Per Day

Endpoints

API v0 Rate Limits (Legacy)

Per Minute

Per Day

Rate Limits by Endpoint

URL Shortening

v1 API Endpoints

v0 API Endpoints (Legacy)

URL Management

Analytics

Authentication & Rate Limits

Rate Limit Headers

Handling Rate Limits

Need Higher Limits?

Next Steps

Create API Keys

API Reference

Quick Start

Python Library

​API v1 Rate Limits (Recommended)

​With Authentication (JWT or API Key)

Per Minute

Per Day

Endpoints

​Without Authentication (Anonymous)

Per Minute

Per Day

Endpoints

​API v0 Rate Limits (Legacy)

Per Minute

Per Day

​Rate Limits by Endpoint

​URL Shortening

​v1 API Endpoints

​v0 API Endpoints (Legacy)

​URL Management

​Analytics

​Authentication & Rate Limits

​Rate Limit Headers

​Handling Rate Limits

​Need Higher Limits?

​Next Steps

Create API Keys

API Reference

Quick Start

Python Library

API v1 Rate Limits (Recommended)

With Authentication (JWT or API Key)

Without Authentication (Anonymous)

API v0 Rate Limits (Legacy)

Rate Limits by Endpoint

URL Shortening

v1 API Endpoints

v0 API Endpoints (Legacy)

URL Management

Analytics

Authentication & Rate Limits

Rate Limit Headers

Handling Rate Limits

Need Higher Limits?

Next Steps