Introduction

The Lurkr API (v2) is a RESTful API that enables seamless integration with Lurkr's features from your own applications. This documentation will help you get started with making requests and handling responses.

Quick Start

Create your API key in your profile page. Make sure to allow access to some servers
Include the API key in the X-API-Key header
Make requests to the base URL: https://api.lurkr.gg/v2

Example request using cURL:

curl -H "X-API-Key: your-api-key" https://api.lurkr.gg/v2/levels/{guildId}/users/{userId}

_{Make sure to replace {guildId} and {userId} with the actual guild and user IDs.}

Versioning

The current version of the API is v2. All endpoints are prefixed with the version number.

Base URL: https://api.lurkr.gg/v2

Authentication

API requests are authenticated using API keys. These keys must be included in the X-API-Key header of every request.

API Key Permissions

There are read-only and read/write API keys:
- Read-only keys can only fetch data, i.e. GET requests.
- Read/Write keys can fetch and modify data, i.e. GET, POST, PATCH, DELETE requests.
By default, API keys have no server access.
Server access must be explicitly granted. Please note that you must either own the server or have Administrator permissions to grant access.

To create and manage your API keys, visit your profile page.

Rate Limiting

The API enforces rate limits to ensure fair usage and system stability. You can make 120 requests per minute per API key.

Rate Limit Headers

Each response includes the following headers to help you manage your API usage:

Header	Description
`X-RateLimit-Limit`	Total number of requests allowed per minute
`X-RateLimit-Remaining`	Number of requests remaining in the current time window
`X-RateLimit-Reset`	Seconds until the rate limit resets
`Retry-After`	Seconds to wait before making new requests (only included when rate limit is exceeded)

Handling Rate Limits

When you hit the rate limit, you'll receive a 429 Too Many Requests response. The Retry-After header will tell you how long to wait before making new requests.

Error Handling

The API uses standard HTTP status codes to indicate success or failure of requests. All error responses include a JSON body with details about the error.

Example error response:

{
    "message": "Invalid API key"
}

Common error codes:

400: Bad Request - Invalid parameters
401: Unauthorized - Missing or invalid API key
403: Forbidden - Insufficient permissions
404: Not Found - Resource doesn't exist
429: Too Many Requests - Rate limit exceeded

API Documentation

For detailed information about available endpoints, parameters, and response formats:

Best Practices

Keep your API keys secure
- Read/Write keys are dangerous and can delete user from your server. Please be mindful when using / sharing them.
- Rotate keys regularly. You can also set an expiration date when creating a key.
- Store the keys in a secure location.
Handle errors gracefully
- Implement proper error handling
- Respect rate limits

Support

If you need help or have questions about the API, join our Discord support server.

On this page