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

# API Reference

> Complete reference for the Limitly REST API

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:

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

```json theme={null}
{
  "data": {
    // Response data
  },
  "count": 1
}
```

## Error Responses

Error responses include an error message and code:

```json theme={null}
{
  "error": "Error message",
  "code": "ERROR_CODE"
}
```

## Common Error Codes

| Code                  | Description                       |
| --------------------- | --------------------------------- |
| `INVALID_API_KEY`     | The API key is invalid or expired |
| `RATE_LIMIT_EXCEEDED` | Rate limit exceeded               |
| `VALIDATION_ERROR`    | Request validation failed         |
| `NOT_FOUND`           | Resource not found                |
| `UNAUTHORIZED`        | Authentication required           |

## Endpoints

### Authentication

* `POST /functions/v1/validate` - Validate a user request

### API Keys

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

### Plans

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

### Users

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

## Data Types

### API Key Object

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

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

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

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

| Code  | Description           |
| ----- | --------------------- |
| `200` | Success               |
| `201` | Created               |
| `400` | Bad Request           |
| `401` | Unauthorized          |
| `404` | Not Found             |
| `429` | Too Many Requests     |
| `500` | Internal Server Error |

## SDKs

For easier integration, use our official SDKs:

* [Node.js SDK](/sdk/installation) - JavaScript/TypeScript SDK
* [Next.js SDK](/sdk/nextjs/installation) - Next.js optimized SDK
* [Python SDK](/sdk/python/installation) - Python SDK

## Support

For API support and questions:

* [Documentation](/docs) - Complete documentation
* [Dashboard](https://app.limitly.com) - Manage your account
* [Contact](mailto:support@limitly.com) - Email support

## Next Steps

* [Authentication](/rest-api/authentication) - Learn how to authenticate
* [Request Validation](/rest-api/validation) - Validate user requests
* [API Key Management](/rest-api/api-keys) - Manage API keys