API Documentation

# API Documentation

**Version:** 2.0
**Base URL:** `https://api.example.com/v2`
**Last Updated:** January 15, 2024

---

## Authentication

All requests require a Bearer token in the Authorization header:

```
Authorization: Bearer YOUR_API_KEY
```

Obtain your API key from the [Developer Dashboard](https://example.com/dashboard).

## Common Headers

| Header | Value | Required |
|--------|-------|----------|
| Authorization | Bearer {token} | Yes |
| Content-Type | application/json | Yes (POST/PUT) |
| Accept | application/json | Recommended |

---

## Endpoints

### List Users

```
GET /users
```

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| page | integer | 1 | Page number |
| limit | integer | 20 | Items per page (max 100) |
| sort | string | created_at | Sort field |

**Response:**

```json
{
  "data": [
    {
      "id": "usr_abc123",
      "name": "Jane Doe",
      "email": "jane@example.com",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 142
  }
}
```

### Create User

```
POST /users
```

**Request Body:**

```json
{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "role": "member"
}
```

**Response:** `201 Created`

```json
{
  "data": {
    "id": "usr_abc123",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "role": "member",
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### Get User

```
GET /users/:id
```

### Update User

```
PUT /users/:id
```

### Delete User

```
DELETE /users/:id
```

**Response:** `204 No Content`

---

## Error Codes

| Status | Code | Description |
|--------|------|-------------|
| 400 | bad_request | Invalid request body or parameters |
| 401 | unauthorized | Missing or invalid API key |
| 403 | forbidden | Insufficient permissions |
| 404 | not_found | Resource does not exist |
| 429 | rate_limited | Too many requests |
| 500 | server_error | Internal server error |

**Error Response Format:**

```json
{
  "error": {
    "code": "not_found",
    "message": "User with id 'usr_xyz' was not found."
  }
}
```

## Rate Limiting

- **Limit:** 1,000 requests per minute
- **Headers:** `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`

## Versioning

The API version is included in the URL path. The current version is `v2`. Version `v1` is deprecated and will be removed on March 1, 2024.