Introduction

Base URL: https://api.upip-academy.com/v1

Protocol: HTTPS only

Format: JSON

Version: 1.0.0

Welcome to the UPIP Academy API! This RESTful API allows developers to integrate our education-tutoring platform into their applications. You can manage students, lessons, tutoring sessions, track progress, and more.

Getting Started

  1. Sign up for a developer account at developer.upip-academy.com
  2. Create an application and obtain your API key
  3. Review the authentication methods below
  4. Start making requests!

Authentication

The UPIP Academy API uses API key authentication. Include your API key in the request header:

Authorization: Bearer YOUR_API_KEY_HERE Content-Type: application/json

Obtaining an API Key

1. Log in to your developer dashboard
2. Navigate to Settings → API Keys
3. Click "Generate New Key"
4. Copy and securely store your key

Security Note: Never expose your API key in client-side code. All API calls should be made from your server.

Authentication Example

// Example using Fetch API fetch('https://api.upip-academy.com/v1/students', { method: 'GET', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' } }) .then(response => response.json()) .then(data => console.log(data));

Students Endpoints

GET /students
Retrieve a list of all students

Query Parameters

Parameter Type Description
page optional integer Page number (default: 1)
limit optional integer Items per page (default: 20, max: 100)
grade optional string Filter by grade level

Response Example

{ "success": true, "data": [ { "id": "stu_123456", "name": "Sarah Johnson", "email": "sarah@example.com", "grade": "10th", "points": 2450, "lessons_completed": 24, "created_at": "2025-01-15T10:30:00Z" } ], "pagination": { "page": 1, "limit": 20, "total": 156 } }
GET /students/:id
Retrieve a specific student by ID

Response Example

{ "success": true, "data": { "id": "stu_123456", "name": "Sarah Johnson", "email": "sarah@example.com", "grade": "10th", "points": 2450, "lessons_completed": 24, "current_streak": 7, "achievements": ["perfect_score", "speed_learner"], "created_at": "2025-01-15T10:30:00Z" } }
POST /students
Create a new student

Request Body

Field Type Description
name required string Student's full name
email required string Valid email address
grade required string Grade level (e.g., "10th")
parent_email optional string Parent/guardian email

Request Example

fetch('https://api.upip-academy.com/v1/students', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ name: 'Emma Davis', email: 'emma@example.com', grade: '9th', parent_email: 'parent@example.com' }) });
PUT /students/:id
Update a student's information
DELETE /students/:id
Delete a student account

Lessons Endpoints

GET /lessons
Retrieve all available lessons

Query Parameters

Parameter Type Description
subject optional string Filter by subject (math, science, english, history)
difficulty optional string Filter by difficulty (beginner, intermediate, advanced)
GET /lessons/:id
Get lesson details
POST /lessons/:id/complete
Mark a lesson as completed

Request Body

{ "student_id": "stu_123456", "score": 95, "time_spent": 1800 }

Tutoring Session Endpoints

POST /tutoring/sessions
Book a tutoring session

Request Body

{ "student_id": "stu_123456", "tutor_id": "tut_789", "subject": "mathematics", "datetime": "2025-11-05T14:00:00Z", "duration": 60 }
GET /tutoring/sessions
List all tutoring sessions
GET /tutoring/tutors
List available tutors

Progress Tracking Endpoints

GET /progress/:student_id
Get student's overall progress

Response Example

{ "success": true, "data": { "student_id": "stu_123456", "lessons_completed": 24, "points_earned": 2450, "time_studied": 66600, "current_streak": 7, "subjects": { "mathematics": {"lessons": 8, "avg_score": 95}, "science": {"lessons": 6, "avg_score": 88}, "english": {"lessons": 7, "avg_score": 92}, "history": {"lessons": 3, "avg_score": 90} } } }
GET /progress/:student_id/report
Generate progress report

Query Parameters

Parameter Type Description
period required string weekly, monthly, quarterly
format optional string json, pdf (default: json)

Webhooks

Webhooks allow you to receive real-time notifications when events occur in your UPIP Academy account.

Supported Events

Event Description
student.created New student registered
lesson.completed Student completed a lesson
achievement.unlocked Student unlocked an achievement
session.booked Tutoring session scheduled
session.completed Tutoring session finished

Webhook Payload Example

{ "event": "lesson.completed", "timestamp": "2025-10-30T15:30:00Z", "data": { "student_id": "stu_123456", "lesson_id": "les_789", "score": 95, "points_earned": 100 } }

Configuring Webhooks

  1. Go to Developer Dashboard → Webhooks
  2. Click "Add Endpoint"
  3. Enter your endpoint URL
  4. Select events to subscribe to
  5. Save and test

Rate Limits

To ensure fair usage and system stability, the API enforces the following rate limits:

Plan Requests per Hour Burst Limit
Free 1,000 50/min
Basic 10,000 200/min
Pro 100,000 500/min
Enterprise Unlimited Custom

Rate Limit Headers

X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 999 X-RateLimit-Reset: 1698764400
429 Too Many Requests: If you exceed the rate limit, you'll receive a 429 status code. Wait until the reset time before making new requests.

Error Codes

The API uses standard HTTP status codes and returns detailed error messages:

Code Status Description
200 OK Request succeeded
201 Created Resource created successfully
400 Bad Request Invalid request format or parameters
401 Unauthorized Invalid or missing API key
403 Forbidden Insufficient permissions
404 Not Found Resource not found
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error occurred

Error Response Format

{ "success": false, "error": { "code": "INVALID_STUDENT_ID", "message": "The provided student ID does not exist", "details": { "student_id": "stu_invalid" } } }

Interactive API Tester

Test API endpoints directly from this documentation:

Try It Out

Response will appear here...