# API Reference

> Complete API reference for zerocut.gg

- Canonical page: https://zerocut.gg/docs/api
- Markdown version: https://zerocut.gg/docs/api.md



# API Reference [#api-reference]

Complete API reference for zerocut.gg user-facing API.

## Authentication [#authentication]

All API requests require an API key passed in the `x-api-key` header:

```bash
curl -H "x-api-key: zerocut.your_api_key_here" \
  https://zerocut.gg/api/v1/profile/get
```

You can create and manage API keys in your [dashboard settings](/app/dashboard/settings/api-keys).

## Rate Limiting [#rate-limiting]

The API enforces a sliding window rate limit of **60 requests per minute** per user account. All API keys belonging to the same account share this limit.

### Response Headers [#response-headers]

Every API response includes rate limit headers:

| Header                  | Description                                     |
| ----------------------- | ----------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed per window (60)        |
| `X-RateLimit-Remaining` | Requests remaining in the current window        |
| `X-RateLimit-Reset`     | Unix timestamp (seconds) when the window resets |

### Rate Limit Exceeded [#rate-limit-exceeded]

When the limit is exceeded, the API returns a `429 Too Many Requests` response with an additional `Retry-After` header indicating how many seconds to wait:

```json
{
  "error": "Rate limit exceeded. Please try again later.",
  "code": "TOO_MANY_REQUESTS"
}
```

### Best Practices [#best-practices]

* Monitor the `X-RateLimit-Remaining` header and back off before hitting 0
* Cache responses client-side when possible
* Use the `Retry-After` header to schedule retries after a 429 response