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

# API Specifications

> Migrated from the previous Learnille internal documentation hub

## Overview

This document provides links and information about the Learnille platform's API specifications.

## API Documentation

### Swagger/OpenAPI Specifications

The Learnille API is documented using OpenAPI 3.0 specification and is available through interactive Swagger UI documentation.

#### Production API Documentation

* **URL**: [https://api.learnille.com/docs](https://api.learnille.com/docs)
* **Swagger UI**: Interactive API explorer
* **OpenAPI JSON**: [https://api.learnille.com/docs/openapi.json](https://api.learnille.com/docs/openapi.json)

#### Development API Documentation

* **URL**: [https://api-dev.learnille.com/docs](https://api-dev.learnille.com/docs)
* **Swagger UI**: Development environment API explorer
* **OpenAPI JSON**: [https://api-dev.learnille.com/docs/openapi.json](https://api-dev.learnille.com/docs/openapi.json)

## API Architecture

### RESTful Design Principles

* **Resource-Based**: APIs are organized around resources (users, courses, etc.)
* **HTTP Methods**: Standard HTTP methods (GET, POST, PUT, DELETE)
* **Stateless**: Each request contains all necessary information
* **HATEOAS**: Hypermedia as the Engine of Application State

### Authentication

All API endpoints require authentication using JWT (JSON Web Tokens).

```http theme={null}
Authorization: Bearer <jwt_token>
```

#### Token Acquisition

```http theme={null}
POST /auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password"
}
```

Response:

```json theme={null}
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600
}
```

### API Versioning

* **Current Version**: v1
* **Version Header**: `Accept: application/vnd.learnille.v1+json`
* **URL Versioning**: `/api/v1/`
* **Deprecation Policy**: 12 months notice for breaking changes

## Core API Endpoints

### User Management API

#### Get User Profile

```http theme={null}
GET /api/v1/users/{id}
Authorization: Bearer {token}
```

#### Update User Profile

```http theme={null}
PUT /api/v1/users/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "first_name": "John",
  "last_name": "Doe",
  "bio": "Learning enthusiast"
}
```

#### List Users

```http theme={null}
GET /api/v1/users?role=student&limit=20&offset=0
Authorization: Bearer {token}
```

### Course Management API

#### List Courses

```http theme={null}
GET /api/v1/courses?category=programming&level=beginner&limit=10
```

#### Get Course Details

```http theme={null}
GET /api/v1/courses/{id}
```

#### Create Course

```http theme={null}
POST /api/v1/courses
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "Introduction to React",
  "description": "Learn React fundamentals",
  "category_id": "uuid",
  "price": 49.99,
  "level": "beginner"
}
```

#### Update Course

```http theme={null}
PUT /api/v1/courses/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "Advanced React",
  "is_published": true
}
```

#### Delete Course

```http theme={null}
DELETE /api/v1/courses/{id}
Authorization: Bearer {token}
```

### Enrollment API

#### Enroll in Course

```http theme={null}
POST /api/v1/enrollments
Authorization: Bearer {token}
Content-Type: application/json

{
  "course_id": "uuid"
}
```

#### Get Enrollment Progress

```http theme={null}
GET /api/v1/enrollments/{id}/progress
Authorization: Bearer {token}
```

#### Update Lesson Progress

```http theme={null}
PUT /api/v1/enrollments/{enrollment_id}/lessons/{lesson_id}/progress
Authorization: Bearer {token}
Content-Type: application/json

{
  "completed": true,
  "time_spent_minutes": 45
}
```

### Payment API

#### Create Payment Intent

```http theme={null}
POST /api/v1/payments/intent
Authorization: Bearer {token}
Content-Type: application/json

{
  "amount": 49.99,
  "currency": "USD",
  "description": "Course enrollment"
}
```

#### Process Payment

```http theme={null}
POST /api/v1/payments/{id}/process
Authorization: Bearer {token}
Content-Type: application/json

{
  "payment_method_id": "pm_1234567890"
}
```

#### Get Payment History

```http theme={null}
GET /api/v1/payments?status=completed&limit=20
Authorization: Bearer {token}
```

### Consultation API

#### List Available Consultations

```http theme={null}
GET /api/v1/consultations?category=programming&available=true
```

#### Book Consultation

```http theme={null}
POST /api/v1/consultations/{id}/book
Authorization: Bearer {token}
Content-Type: application/json

{
  "scheduled_at": "2024-01-15T14:00:00Z"
}
```

#### Get Consultation Details

```http theme={null}
GET /api/v1/consultations/{id}
Authorization: Bearer {token}
```

### Search API

#### Search Courses

```http theme={null}
GET /api/v1/search/courses?q=react&category=programming&level=beginner
```

#### Search Users

```http theme={null}
GET /api/v1/search/users?q=john&role=instructor
```

## Response Format

### Success Response

```json theme={null}
{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "Example",
    "created_at": "2024-01-01T00:00:00Z"
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00Z",
    "request_id": "req_123456"
  }
}
```

### Error Response

```json theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": {
      "field": "email",
      "reason": "Invalid email format"
    }
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00Z",
    "request_id": "req_123456"
  }
}
```

## Rate Limiting

* **Authenticated Requests**: 1000 requests per hour
* **Unauthenticated Requests**: 100 requests per hour
* **Search Requests**: 50 requests per hour

Rate limit headers:

```http theme={null}
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
```

## Pagination

```http theme={null}
GET /api/v1/courses?limit=20&offset=0
```

Response:

```json theme={null}
{
  "success": true,
  "data": [...],
  "meta": {
    "pagination": {
      "total": 150,
      "limit": 20,
      "offset": 0,
      "has_more": true
    }
  }
}
```

## Filtering and Sorting

### Filtering

```http theme={null}
GET /api/v1/courses?category=programming&level=beginner&price_min=0&price_max=100
```

### Sorting

```http theme={null}
GET /api/v1/courses?sort=created_at&order=desc
GET /api/v1/courses?sort=rating&order=desc
```

## Webhooks

### Payment Webhooks

```http theme={null}
POST /api/v1/webhooks/stripe
X-Signature: stripe_signature

{
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "id": "pi_1234567890",
      "amount": 4999,
      "currency": "usd"
    }
  }
}
```

## SDKs and Libraries

### JavaScript SDK

```javascript theme={null}
import { LearnilleAPI } from 'learnille-sdk';

const client = new LearnilleAPI({
  apiKey: 'your-api-key',
  baseURL: 'https://api.learnille.com'
});

// Get courses
const courses = await client.courses.list({
  category: 'programming',
  limit: 10
});
```

### Python SDK

```python theme={null}
from learnille_sdk import LearnilleAPI

client = LearnilleAPI(
    api_key='your-api-key',
    base_url='https://api.learnille.com'
)

# Get courses
courses = client.courses.list(category='programming', limit=10)
```

## API Testing

### Using cURL

```bash theme={null}
# Get courses
curl -X GET "https://api.learnille.com/api/v1/courses" \
  -H "Authorization: Bearer your-jwt-token"

# Create course
curl -X POST "https://api.learnille.com/api/v1/courses" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{"title": "New Course", "description": "Course description"}'
```

### Using Postman

* Import OpenAPI specification
* Set up environment variables for tokens
* Use collection runner for automated testing

## Error Codes

| Code | Description |
| - | - |
| 400 | Bad Request - Invalid input |
| 401 | Unauthorized - Invalid/missing token |
| 403 | Forbidden - Insufficient permissions |
| 404 | Not Found - Resource doesn't exist |
| 409 | Conflict - Resource already exists |
| 422 | Unprocessable Entity - Validation failed |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error - Server error |

## Support

For API support and questions:

* **Documentation**: [https://docs.learnille.com](https://docs.learnille.com)
* **Developer Forum**: [https://community.learnille.com](https://community.learnille.com)
* **Email Support**: [api-support@learnille.com](mailto:api-support@learnille.com)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.