API & Integrations

Quick Start

Get up and running with the LearnFlow API in under 5 minutes. Follow these steps to make your first API call.

1. 1

   Get Your API Key

   Navigate to Settings → Developer → API Keys in your LearnFlow dashboard. Generate a new key with the required permissions.

2. 2

   Make Your First Request

   Use your API key to authenticate requests. Here's a simple example to fetch all users:

3. 3

   Explore the API

   Use our Postman collection or SDKs to explore all available endpoints. Check the API Reference for detailed documentation.

 Copycurl -X GET "https://api.learnflow.com/v2/users" \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json"

Authentication

LearnFlow uses API keys for authentication. Every request must include your API key in the Authorization header. You can manage your API keys from the Developer Dashboard.

API Key Authentication

Include your API key as a Bearer token in the Authorization header:

 CopyAuthorization: Bearer sk_live_your_api_key_here

OAuth 2.0 (User Authorization)

For applications that act on behalf of users, LearnFlow supports OAuth 2.0 with PKCE. This allows users to authorize your application to access their learning data without sharing credentials.

 Copy// Step 1: Redirect user to authorization URL
const authUrl = new URL('https://api.learnflow.com/oauth/authorize');
authUrl.searchParams.set('client_id', 'your_client_id');
authUrl.searchParams.set('redirect_uri', 'https://yourapp.com/callback');
authUrl.searchParams.set('response_type', 'code');
authUrl.searchParams.set('scope', 'read:enrollments read:progress');
authUrl.searchParams.set('state', 'random_csrf_token');

// Step 2: Exchange code for access token
const response = await fetch('https://api.learnflow.com/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'authorization_code',
    client_id: 'your_client_id',
    client_secret: 'your_client_secret',
    code: 'authorization_code_from_callback',
    redirect_uri: 'https://yourapp.com/callback',
    code_verifier: 'your_code_verifier'
  })
});

Available Scopes

Rate Limits

API rate limits are based on your subscription tier. If you exceed your rate limit, you'll receive a 429 Too Many Requests response. Rate limit information is included in response headers.

 CopyResponse Headers:
x-ratelimit-limit: 500
x-ratelimit-remaining: 498
x-ratelimit-reset: 1699900800
x-request-id: req_abc123def456

Error Handling

LearnFlow uses conventional HTTP status codes to indicate the success or failure of requests. Codes in the 2xx range indicate success, 4xx range indicate client errors, and 5xx range indicate server errors.

 Copy{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The user with id 'usr_12345' does not exist.",
    "param": "user_id",
    "request_id": "req_abc123def456"
  }
}

Common Error Codes

API Reference

The LearnFlow API provides RESTful endpoints for managing all aspects of your learning platform. Below are the core endpoints organized by resource.

List Users

 Copy{
  "data": [
    {
      "id": "usr_2xKj9mNpQr",
      "email": "sarah.johnson@example.com",
      "name": "Sarah Johnson",
      "role": "student",
      "status": "active",
      "avatar_url": "https://cdn.learnflow.com/avatars/usr_2xKj9mNpQr.jpg",
      "created_at": "2024-01-15T08:30:00Z",
      "last_login": "2024-03-14T14:22:00Z",
      "enrolled_courses": 5,
      "completed_courses": 2
    },
    {
      "id": "usr_8hRt4vLwMn",
      "email": "michael.chen@example.com",
      "name": "Michael Chen",
      "role": "instructor",
      "status": "active",
      "avatar_url": null,
      "created_at": "2024-02-01T10:15:00Z",
      "last_login": "2024-03-14T09:45:00Z",
      "enrolled_courses": 0,
      "completed_courses": 0
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 20,
    "total_pages": 12,
    "total_count": 234,
    "has_next": true,
    "has_prev": false
  },
  "request_id": "req_abc123def456"
}

 Copy{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or has been revoked.",
    "request_id": "req_xyz789abc012"
  }
}

Create User

 Copycurl -X POST "https://api.learnflow.com/v2/users" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe@example.com",
    "name": "John Doe",
    "role": "student",
    "metadata": {
      "department": "Engineering",
      "employee_id": "EMP-2024-001"
    }
  }'

 Copy{
  "data": {
    "id": "usr_5pQw3xYzAb",
    "email": "john.doe@example.com",
    "name": "John Doe",
    "role": "student",
    "status": "invited",
    "avatar_url": null,
    "metadata": {
      "department": "Engineering",
      "employee_id": "EMP-2024-001"
    },
    "created_at": "2024-03-14T16:30:00Z",
    "invitation_sent_at": "2024-03-14T16:30:00Z",
    "invitation_expires_at": "2024-03-21T16:30:00Z"
  },
  "request_id": "req_def456ghi789"
}

List Courses

 Copy{
  "data": [
    {
      "id": "crs_4mNp7qRsT",
      "title": "Complete Web Development Bootcamp",
      "slug": "web-dev-bootcamp-2024",
      "description": "Master full-stack web development from scratch.",
      "category": "Development",
      "level": "beginner",
      "instructor": {
        "id": "usr_8hRt4vLwMn",
        "name": "Michael Chen"
      },
      "thumbnail_url": "https://cdn.learnflow.com/courses/crs_4mNp7qRsT/thumb.jpg",
      "duration_hours": 42,
      "total_lessons": 186,
      "enrolled_count": 1243,
      "average_rating": 4.9,
      "is_published": true,
      "created_at": "2024-01-10T00:00:00Z",
      "updated_at": "2024-03-10T00:00:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 20,
    "total_pages": 5,
    "total_count": 87
  }
}

Enroll User in Course

 Copy{
  "data": {
    "id": "enr_9kLm2nPqR",
    "user_id": "usr_2xKj9mNpQr",
    "course_id": "crs_4mNp7qRsT",
    "status": "active",
    "enrolled_at": "2024-03-14T16:35:00Z",
    "last_accessed_at": null,
    "completed_at": null,
    "progress": {
      "current_lesson": 1,
      "total_lessons": 186,
      "percent_complete": 0,
      "time_spent_minutes": 0
    }
  },
  "request_id": "req_ghi789jkl012"
}

Get User Progress

 Copy{
  "data": {
    "user_id": "usr_2xKj9mNpQr",
    "user_name": "Sarah Johnson",
    "total_enrolled": 5,
    "total_completed": 2,
    "total_time_spent_minutes": 3420,
    "courses": [
      {
        "course_id": "crs_4mNp7qRsT",
        "course_title": "Complete Web Development Bootcamp",
        "status": "in_progress",
        "current_lesson": 47,
        "total_lessons": 186,
        "percent_complete": 25.3,
        "last_accessed_at": "2024-03-14T14:22:00Z",
        "time_spent_minutes": 1580
      },
      {
        "course_id": "crs_7wXy1zAbC",
        "course_title": "Python for Data Science",
        "status": "completed",
        "current_lesson": 120,
        "total_lessons": 120,
        "percent_complete": 100,
        "completed_at": "2024-02-28T18:00:00Z",
        "time_spent_minutes": 1200,
        "certificate_id": "cert_3dEf6gHiJ"
      }
    ]
  }
}

Get Certificates

 Copy{
  "data": [
    {
      "id": "cert_3dEf6gHiJ",
      "user_id": "usr_2xKj9mNpQr",
      "user_name": "Sarah Johnson",
      "course_id": "crs_7wXy1zAbC",
      "course_title": "Python for Data Science",
      "issued_at": "2024-02-28T18:00:00Z",
      "certificate_url": "https://learnflow.com/certificates/cert_3dEf6gHiJ",
      "verification_url": "https://learnflow.com/verify/cert_3dEf6gHiJ",
      "credential_id": "lf:cert:3dEf6gHiJ",
      "download_urls": {
        "pdf": "https://cdn.learnflow.com/certs/cert_3dEf6gHiJ.pdf",
        "png": "https://cdn.learnflow.com/certs/cert_3dEf6gHiJ.png",
        "svg": "https://cdn.learnflow.com/certs/cert_3dEf6gHiJ.svg"
      }
    }
  ]
}

Manage Webhook Endpoints

Integration Hub

Connect LearnFlow with your existing tools and platforms. Our integration hub provides pre-built connectors for popular services, as well as flexible APIs for custom integrations.

Official SDKs

Use our official SDKs to interact with the LearnFlow API in your preferred programming language. All SDKs are open-source and available on GitHub.

SDK Example (Python)

 Copyimport learnflow

# Initialize the client
learnflow.api_key = "sk_live_your_api_key"

# List users
users = learnflow.User.list(
    page=1,
    per_page=50,
    role="student",
    status="active"
)

# Create a user
new_user = learnflow.User.create(
    email="new.user@example.com",
    name="New User",
    role="student",
    metadata={"department": "Engineering"}
)
print(f"Created user: {new_user.id}")

# Enroll user in a course
enrollment = learnflow.Enrollment.create(
    user_id=new_user.id,
    course_id="crs_4mNp7qRsT"
)
print(f"Enrollment status: {enrollment.status}")

# Get user progress
progress = learnflow.User.progress(user_id=new_user.id)
print(f"Total time spent: {progress.total_time_spent_minutes} minutes")

Postman Collection

Import our Postman collection to quickly test all API endpoints with pre-configured environments for both sandbox and live.

OpenAPI Specification

The complete OpenAPI 3.0 specification is available for download or online viewing. Use it to generate client code in any language or to explore the API interactively.

Webhooks

Webhooks allow you to receive real-time notifications when events occur in your LearnFlow account. Configure webhook endpoints to listen for specific events and take automatic actions in your own systems.

Available Events

Webhook Payload

All webhook events are delivered as POST requests to your configured URL. The payload includes the event type, timestamp, and event-specific data.

 Copy{
  "id": "evt_1NtQ7mKpR2",
  "type": "enrollment.completed",
  "created_at": "2024-03-14T16:35:00Z",
  "data": {
    "enrollment_id": "enr_9kLm2nPqR",
    "user_id": "usr_2xKj9mNpQr",
    "user_name": "Sarah Johnson",
    "course_id": "crs_4mNp7qRsT",
    "course_title": "Complete Web Development Bootcamp",
    "completed_at": "2024-03-14T16:35:00Z",
    "certificate_id": "cert_8kLm2nPqR",
    "total_time_minutes": 2520,
    "average_quiz_score": 92.5
  },
  "metadata": {
    "webhook_id": "wh_3xYz5aBcD",
    "attempt": 1
  }
}

Verifying Webhook Signatures

LearnFlow signs all webhook payloads using HMAC-SHA256. Verify the signature using the X-LearnFlow-Signature header and your webhook secret.

 Copy// Node.js example for verifying webhook signatures
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from('whsec_' + expectedSignature)
  );
}

// In your webhook handler:
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-learnflow-signature'];
  const payload = JSON.stringify(req.body);

  if (!verifyWebhook(payload, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Process the webhook event
  handleEvent(req.body);
  res.status(200).json({ received: true });
});

API Changelog

We track all changes to the API for transparency. Current version: v2.4.1 (March 2024).

FAQ

Support

Need help with the API? We're here to assist.