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

# Users API

> API endpoints for managing user accounts and profiles.

# Users API

The Users API allows you to manage user accounts, profiles, and preferences.

## Base URL

```
https://api.readingsteps.uk/v1/users
```

## Get Current User

Retrieve the authenticated user's profile information.

```bash theme={null}
GET /users/me
Authorization: Bearer YOUR_ACCESS_TOKEN
```

### Response

```json theme={null}
{
  "id": "usr_abc123",
  "email": "user@example.com",
  "name": "John Doe",
  "avatar": "https://cdn.readingsteps.uk/avatars/usr_abc123.jpg",
  "reading_level": "intermediate",
  "created_at": "2024-01-15T10:30:00Z",
  "preferences": {
    "font_size": 16,
    "theme": "light",
    "notifications": true
  }
}
```

## Get User by ID

Retrieve a specific user's public profile.

```bash theme={null}
GET /users/{user_id}
Authorization: Bearer YOUR_ACCESS_TOKEN
```

### Parameters

| Parameter | Type   | Required | Description                  |
| --------- | ------ | -------- | ---------------------------- |
| user\_id  | string | Yes      | The user's unique identifier |

### Response

```json theme={null}
{
  "id": "usr_abc123",
  "name": "John Doe",
  "avatar": "https://cdn.readingsteps.uk/avatars/usr_abc123.jpg",
  "reading_level": "intermediate",
  "books_read": 42,
  "member_since": "2024-01-15"
}
```

## Update User Profile

Update the authenticated user's profile information.

```bash theme={null}
PATCH /users/me
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "name": "Jane Doe",
  "avatar": "https://example.com/avatar.jpg",
  "preferences": {
    "font_size": 18,
    "theme": "dark"
  }
}
```

### Request Body

| Field       | Type   | Required | Description                |
| ----------- | ------ | -------- | -------------------------- |
| name        | string | No       | User's display name        |
| avatar      | string | No       | URL to user's avatar image |
| preferences | object | No       | User preferences object    |

### Response

```json theme={null}
{
  "id": "usr_abc123",
  "email": "user@example.com",
  "name": "Jane Doe",
  "avatar": "https://example.com/avatar.jpg",
  "preferences": {
    "font_size": 18,
    "theme": "dark",
    "notifications": true
  }
}
```

## Delete User Account

Permanently delete the authenticated user's account.

```bash theme={null}
DELETE /users/me
Authorization: Bearer YOUR_ACCESS_TOKEN
```

### Response

```json theme={null}
{
  "success": true,
  "message": "Account deleted successfully"
}
```

## Get User Reading Stats

Retrieve detailed reading statistics for a user.

```bash theme={null}
GET /users/{user_id}/stats
Authorization: Bearer YOUR_ACCESS_TOKEN
```

### Response

```json theme={null}
{
  "user_id": "usr_abc123",
  "total_reading_time": 125000,
  "books_completed": 42,
  "pages_read": 12500,
  "average_reading_speed": 250,
  "vocabulary_size": 3500,
  "current_streak": 15,
  "longest_streak": 30
}
```

## Error Responses

All endpoints may return the following errors:

| Status Code | Error                | Description                     |
| ----------- | -------------------- | ------------------------------- |
| 401         | Unauthorized         | Invalid or expired access token |
| 403         | Forbidden            | Insufficient permissions        |
| 404         | Not Found            | User does not exist             |
| 422         | Unprocessable Entity | Invalid request data            |
| 429         | Too Many Requests    | Rate limit exceeded             |

### Example Error Response

```json theme={null}
{
  "error": {
    "code": "user_not_found",
    "message": "The requested user could not be found",
    "details": {}
  }
}
```