Complete reference for the Limitly REST API endpoints, parameters, and responses.

​
Base URL

All API requests should be made to: 
https://api.limitly.dev

​
Authentication

All API requests require authentication using your API key in the Authorization header: 
Authorization: Bearer lk_1234567890abcdef1234567890abcdef

​
API Versioning

The current API version is v1. All endpoints are prefixed with /v1/.

​
Rate Limiting

The Limitly API itself is rate limited to 1000 requests per minute per API key.

​
Common Response Format

All API responses follow this format: 
{
  "data": {
    // Response data
  },
  "count": 1
}

​
Error Responses

Error responses include an error message and code: 
{
  "error": "Error message",
  "code": "ERROR_CODE"
}

​
Common Error Codes

CodeDescription
INVALID_API_KEYThe API key is invalid or expired
RATE_LIMIT_EXCEEDEDRate limit exceeded
VALIDATION_ERRORRequest validation failed
NOT_FOUNDResource not found
UNAUTHORIZEDAuthentication required

​
Endpoints

​
Authentication

  • POST /v1/validate - Validate a user request

​
API Keys

  • GET /v1/keys - List all API keys
  • POST /v1/keys - Create a new API key
  • GET /v1/keys/{id} - Get API key details
  • PUT /v1/keys/{id} - Update an API key
  • DELETE /v1/keys/{id} - Delete an API key
  • POST /v1/keys/{id}/regenerate - Regenerate an API key
  • GET /v1/keys/{id}/usage - Get API key usage
  • GET /v1/keys/{id}/requests - Get API key request history

​
Plans

  • GET /v1/plans - List all plans
  • POST /v1/plans - Create a new plan
  • GET /v1/plans/{id} - Get plan details
  • PUT /v1/plans/{id} - Update a plan
  • DELETE /v1/plans/{id} - Delete a plan
  • GET /v1/plans/{id}/usage - Get plan usage
  • GET /v1/plans/{id}/users - Get plan users
  • GET /v1/plans/{id}/keys - Get plan API keys

​
Users

  • GET /v1/users - List all users
  • POST /v1/users - Create a new user
  • GET /v1/users/{id} - Get user details
  • PUT /v1/users/{id} - Update a user
  • DELETE /v1/users/{id} - Delete a user
  • GET /v1/users/{id}/usage - Get user usage
  • GET /v1/users/{id}/keys - Get user API keys
  • GET /v1/users/{id}/requests - Get user request history

​
Data Types

​
API Key Object

{
  "id": "key_123",
  "api_key": "lk_user_abcdef1234567890abcdef1234567890",
  "name": "Production API Key",
  "user_id": 123,
  "plan_id": "plan_456",
  "status": "active",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

​
Plan Object

{
  "id": "plan_123",
  "name": "Basic Plan",
  "description": "Plan for basic users",
  "max_requests": 10000,
  "request_period": "month",
  "is_active": true,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

​
User Object

{
  "user_id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "is_disabled": false,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

​
Validation Response

{
  "success": true,
  "details": {
    "current_usage": 45,
    "limit": 1000,
    "remaining": 955,
    "reset_time": "2024-02-01T00:00:00Z",
    "plan_name": "Basic Plan"
  }
}

​
Pagination

List endpoints support pagination with query parameters:
  • page - Page number (default: 1)
  • limit - Items per page (default: 10, max: 100)

​
HTTP Status Codes

CodeDescription
200Success
201Created
400Bad Request
401Unauthorized
404Not Found
429Too Many Requests
500Internal Server Error

​
SDKs

For easier integration, use our official SDKs:

​
Support

For API support and questions:

​
Next Steps