LearnFlow API Documentation

Welcome to the LearnFlow REST API. This documentation covers all endpoints, authentication methods, and integration patterns for building applications that interact with our learning management platform. The API is designed around REST principles and returns JSON responses.

Base URL: All API requests should be made to https://api.learnflow.com/v1. Sandbox testing is available at https://api-sandbox.learnflow.com/v1.

Authentication

The LearnFlow API uses Bearer Token authentication for secure access. All requests must include an Authorization header with a valid API key or OAuth2 access token.

Authorization: Bearer YOUR_API_KEY_HERE

Scopes: Access is controlled via OAuth2 scopes. Available scopes include read:courses, write:enrollments, admin:users, and read:analytics.

Course Management

Endpoints for retrieving, creating, and updating course content and metadata.

GET /courses

Retrieve a paginated list of all available courses. Supports filtering by category, difficulty, and status.

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Results per page (default: 20, max: 100)
`category`	string	Filter by category slug
`status`	string	`published`, `draft`, `archived`

Response (200 OK)

{
  "data": [
    {
      "id": "course_8f3a2c1d",
      "title": "Advanced React Patterns",
      "category": "frontend",
      "instructor_id": "user_9b2e4f1a",
      "enrolled_count": 142,
      "status": "published",
      "created_at": "2024-01-15T08:30:00Z"
    }
  ],
  "meta": {
    "total": 128,
    "page": 1,
    "limit": 20
  }
}

POST /courses

Create a new course. Requires write:courses scope.

Request Body

Parameter	Type	Required	Description
`title`	string	Required	Course title (max 100 chars)
`description`	string	Required	Markdown-formatted course description
`category_id`	string	Required	Valid category identifier
`thumbnail_url`	string	Optional	Direct URL to course cover image

Enrollments

Manage student enrollments, track progress, and retrieve completion status.

POST /enrollments

Enroll a user in a course. Triggers welcome emails and initializes progress tracking.

Request Body

{
  "user_id": "user_x7k9m2p1",
  "course_id": "course_8f3a2c1d",
  "plan_id": "plan_professional", // Optional
}

Response (201 Created)

{
  "enrollment_id": "enroll_3d8f2a1c",
  "status": "active",
  "progress": 0,
  "started_at": "2024-03-10T14:22:00Z"
}

Error Codes

LearnFlow uses standard HTTP status codes and returns detailed error objects in the response body.

Code	Status	Description
400	Bad Request	Missing or invalid parameters
401	Unauthorized	Invalid or missing API key
403	Forbidden	Insufficient permissions/scope
404	Not Found	Resource does not exist
429	Too Many Requests	Rate limit exceeded
500	Server Error	Internal platform error

Error Format: All errors return a JSON object with error.code, error.message, and error.details (when applicable).

SDKs & Libraries

Official client libraries are available for popular frameworks to simplify integration:

Community-maintained packages are also available for PHP, Go, and Dart.