Build powerful educational applications with our RESTful API
Welcome to the SmartGradeAI API! Our RESTful API allows you to integrate AI-powered quiz generation and grading capabilities into your applications.
https://smartgradeai.polimas.net/api/v1
# Get your API key from the dashboard
API_KEY="your_api_key_here"
# Make your first API call
curl -X GET "https://smartgradeai.polimas.net/api/v1/courses" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json"SmartGradeAI API uses Bearer token authentication. Include your API key in the Authorization header of all requests.
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/jsonThe API returns rate limit information in response headers:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200// Example: Handling rate limits in JavaScript
async function makeAPICall(endpoint) {
const response = await fetch(endpoint, {
headers: {
'Authorization': `Bearer ${API_KEY}`
}
});
if (response.status === 429) {
const retryAfter = response.headers.get('Retry-After');
console.log(`Rate limited. Retry after ${retryAfter} seconds`);
// Implement exponential backoff
await sleep(retryAfter * 1000);
return makeAPICall(endpoint);
}
return response.json();
}The API uses standard HTTP status codes and returns JSON error responses.
{
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "The requested quiz was not found",
"details": {
"quiz_id": 123
},
"timestamp": "2024-01-15T10:30:00Z"
}
}| Status Code | Error Code | Description |
|---|---|---|
| 400 | BAD_REQUEST |
Invalid request parameters |
| 401 | UNAUTHORIZED |
Missing or invalid API key |
| 403 | FORBIDDEN |
Access denied to resource |
| 404 | NOT_FOUND |
Resource not found |
| 429 | RATE_LIMITED |
Too many requests |
| 500 | INTERNAL_ERROR |
Server error |
Authenticate user and obtain access token.
{
"username": "user@example.com",
"password": "securepassword"
}{
"success": true,
"data": {
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 3600,
"user": {
"id": 1,
"username": "john_doe",
"email": "user@example.com",
"role": "lecturer"
}
}
}Refresh access token using refresh token.
{
"refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}Retrieve list of quizzes with optional filters.
| Parameter | Type | Required | Description |
|---|---|---|---|
course_id |
integer | Optional | Filter by course ID |
status |
string | Optional | Filter by status (published, draft) |
page |
integer | Optional | Page number (default: 1) |
limit |
integer | Optional | Items per page (default: 20, max: 100) |
{
"success": true,
"data": {
"quizzes": [
{
"id": 1,
"title": "Chapter 1 Quiz",
"description": "Introduction to Programming",
"course_id": 5,
"total_marks": 100,
"duration_minutes": 60,
"is_published": true,
"created_at": "2024-01-15T10:00:00Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 45,
"pages": 3
}
}
}Create a new quiz.
{
"course_id": 5,
"title": "Midterm Exam",
"description": "Covers chapters 1-5",
"quiz_type": "exam",
"total_marks": 100,
"duration_minutes": 120,
"start_datetime": "2024-02-01T09:00:00Z",
"end_datetime": "2024-02-01T11:00:00Z",
"attempts_allowed": 1,
"instructions": "Read all questions carefully",
"is_published": false
}{
"success": true,
"data": {
"quiz_id": 123,
"message": "Quiz created successfully"
}
}Generate quiz questions using AI based on topic and parameters.
{
"topic": "Data Structures and Algorithms",
"difficulty": "medium",
"questions": {
"mcq": 5,
"short_answer": 3,
"essay": 2
},
"language": "en",
"context": "Computer Science undergraduate level"
}{
"success": true,
"data": {
"questions": [
{
"type": "mcq",
"question": "What is the time complexity of binary search?",
"options": [
"O(n)",
"O(log n)",
"O(n²)",
"O(1)"
],
"correct_answer": "O(log n)",
"explanation": "Binary search divides the search space in half...",
"marks": 2
}
],
"metadata": {
"total_questions": 10,
"generation_time": 3.2,
"tokens_used": 1500
}
}
}Get AI-powered grading suggestions for student answers.
{
"question": "Explain the concept of recursion in programming",
"student_answer": "Recursion is when a function calls itself...",
"max_marks": 10,
"grading_criteria": "Clarity, accuracy, examples"
}{
"success": true,
"data": {
"suggested_score": 8,
"feedback": "Good explanation with clear understanding...",
"strengths": ["Clear definition", "Good example"],
"improvements": ["Could include more complex examples"],
"confidence": 0.85
}
}Test API endpoints directly from your browser.
Official JavaScript SDK for browser and Node.js
npm install smartgradeai-sdkJava SDK for SmartGradeAI API
<dependency>
<groupId>com.smartgradeai</groupId>
<artifactId>sdk</artifactId>
</dependency>Download our Postman collection to quickly test all API endpoints.
Complete collection with all endpoints, examples, and test scripts.
Initial release of SmartGradeAI API