> ## Documentation Index
> Fetch the complete documentation index at: https://spoo.me/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API Rate Limits

> Understanding Spoo.me API rate limits and best practices

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)

<CardGroup cols={3}>
  <Card title="Per Minute" icon="clock" color="#10B981">
    **60 requests**
  </Card>

  <Card title="Per Day" icon="calendar-days" color="#10B981">
    **5,000 requests**
  </Card>

  <Card title="Endpoints" icon="code" color="#10B981">
    All v1 endpoints
  </Card>
</CardGroup>

### Without Authentication (Anonymous)

<CardGroup cols={3}>
  <Card title="Per Minute" icon="clock" color="#F59E0B">
    **20 requests**
  </Card>

  <Card title="Per Day" icon="calendar-days" color="#F59E0B">
    **200 requests**
  </Card>

  <Card title="Endpoints" icon="code" color="#F59E0B">
    Limited endpoints
  </Card>
</CardGroup>

<Tip>
  **Get far higher limits** by using [API keys](/docs/api-keys) or JWT authentication: 60 vs 20 requests per minute, and 5,000 vs 200 requests per day.
</Tip>

## API v0 Rate Limits (Legacy)

The legacy v0 API has lower rate limits:

<CardGroup cols={2}>
  <Card title="Per Minute" icon="clock" color="#EF4444">
    **5 short URLs** per IP
  </Card>

  <Card title="Per Day" icon="calendar-days" color="#EF4444">
    **50 short URLs** per IP
  </Card>
</CardGroup>

<Warning>
  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.
</Warning>

## 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)

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

| 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:

<AccordionGroup>
  <Accordion title="API Key Authentication (Recommended)" icon="key">
    **Rate Limits**: 60/min, 5000/day

    **Benefits**:

    * 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](/docs/api-keys) and include it in the `Authorization` header:

    ```bash theme={null}
    Authorization: Bearer spoo_YOUR_API_KEY
    ```
  </Accordion>

  <Accordion title="JWT Token Authentication" icon="shield-check">
    **Rate Limits**: 60/min, 5000/day

    **Benefits**:

    * 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:

    ```bash theme={null}
    Authorization: Bearer YOUR_JWT_TOKEN
    ```
  </Accordion>

  <Accordion title="Anonymous (No Authentication)" icon="user">
    **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.
  </Accordion>
</AccordionGroup>

## Rate Limit Headers

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

```http theme={null}
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:

```json theme={null}
{
  "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:

<Steps>
  <Step title="Contact Support">
    If you still need higher limits, contact our support team at [support@spoo.me](mailto:support@spoo.me) with:

    * Details about your use case
    * Expected request volume
    * Description of your application
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Create API Keys" icon="key" href="/docs/api-keys">
    Get started with API key authentication
  </Card>

  <Card title="API Reference" icon="code" href="/docs/api-reference">
    Explore all available endpoints
  </Card>

  <Card title="Quick Start" icon="rocket" href="/docs/quickstart">
    Build your first integration
  </Card>

  <Card title="Python Library" icon="python" href="/docs/tools/python-library">
    Use our official SDK
  </Card>
</CardGroup>


## Related topics

- [Spoo.me Python SDK](/docs/tools/python-library.md)
- [API Keys](/docs/api-keys.md)
- [SpooBot](/docs/tools/spoobot.md)
- [Creating Discord Webhooks](/docs/self-hosting/creating-discord-webhooks.md)
- [Create Shortened URL](/docs/api-reference/url-shortening/create-shortened-url.md)