Comprehensive guide for integrating with the ProctorAI platform
The ProctorAI API allows you to integrate our advanced exam proctoring capabilities into your own applications and learning management systems. This documentation provides details on how to use our API endpoints to submit exam data, manage recordings, and verify user identity.
Our API is organized around REST principles. All requests should be made over HTTPS, and all response data is returned as JSON.
The ProctorAI API is designed to be integrated with your Learning Management System. The base URL will be configured by you (the client) on your own server infrastructure.
In the examples below, we use {YOUR_API_BASE_URL} as a placeholder. You should replace this with your actual API server URL where you've implemented the ProctorAI API.
Since the ProctorAI API is hosted on your own server infrastructure, you will be responsible for implementing and managing authentication for your API endpoints. We recommend using API keys or another secure authentication method of your choice.
Regardless of the authentication method you choose, be sure to keep your credentials secure. Do not share your API keys or other authentication credentials in publicly accessible areas such as GitHub, client-side code, etc.
// Using Authorization header (example implementation)
fetch('{YOUR_API_BASE_URL}/exams', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_API_KEY'
},
body: JSON.stringify({
// request body
})
})/examsCreate a new exam session
The title of the exam
Duration in minutes
Proctoring settings (webcam, screen recording, etc.)
fetch('{YOUR_API_BASE_URL}/exams', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_API_KEY'
},
body: JSON.stringify({
"title": "Final Computer Science Exam",
"duration": 180,
"settings": {
"webcam": true,
"screenRecording": true,
"audioRecording": true,
"browserLock": true,
"aiDetection": {
"enabled": true,
"sensitivity": "high"
}
}
})
}){
"id": "exam_12345",
"title": "Final Computer Science Exam",
"duration": 180,
"settings": {
"webcam": true,
"screenRecording": true,
"audioRecording": true,
"browserLock": true,
"aiDetection": {
"enabled": true,
"sensitivity": "high"
}
},
"status": "created",
"createdAt": "2025-03-26T14:30:00Z",
"accessUrl": "https://proctor.ai/exam/12345",
"adminUrl": "https://proctor.ai/admin/exam/12345"
}/exams/{exam_id}Retrieve an exam session by ID
The unique identifier for the exam
fetch('{YOUR_API_BASE_URL}/exams/exam_12345', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
}){
"id": "exam_12345",
"title": "Final Computer Science Exam",
"duration": 180,
"settings": {
"webcam": true,
"screenRecording": true,
"audioRecording": true,
"browserLock": true,
"aiDetection": {
"enabled": true,
"sensitivity": "high"
}
},
"status": "in_progress",
"createdAt": "2025-03-26T14:30:00Z",
"startedAt": "2025-03-26T15:00:00Z",
"participants": [
{
"id": "user_789",
"name": "Jane Smith",
"status": "active",
"joinedAt": "2025-03-26T15:00:00Z"
}
],
"warnings": [
{
"timestamp": "2025-03-26T15:15:22Z",
"type": "tab_switch",
"userId": "user_789",
"details": "User switched to another tab"
}
]
}/exams/{exam_id}/submitSubmit exam session data including recordings
The unique identifier for the exam
Session statistics including duration, browser info, etc.
Array of warning events that occurred during the exam
Webcam recording (file upload or base64 encoded string)
Screen recording (file upload or base64 encoded string)
See the Data Formats section for detailed examples of how to structure your request.
/verify/userVerify user identity using facial recognition
The unique identifier for the user
Base64 encoded reference image of the user
Base64 encoded image to verify against the reference
fetch('{YOUR_API_BASE_URL}/verify/user', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_API_KEY'
},
body: JSON.stringify({
"userId": "user_789",
"referenceImage": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEA...",
"verificationImage": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEA..."
})
}){
"verified": true,
"confidence": 0.98,
"matchScore": 0.96,
"faceDetected": true,
"warnings": []
}/recordingsUpload exam recordings (webcam and screen)
The unique identifier for the exam
The unique identifier for the user
Type of recording (webcam or screen)
The recording file
/recordings/{recording_id}Retrieve a specific recording
The unique identifier for the recording
fetch('{YOUR_API_BASE_URL}/recordings/rec_67890', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
}){
"id": "rec_67890",
"examId": "exam_12345",
"userId": "user_789",
"type": "webcam",
"duration": 3600,
"size": 256000000,
"format": "webm",
"createdAt": "2025-03-26T15:30:00Z",
"url": "{YOUR_API_BASE_URL}/recordings/rec_67890/download",
"status": "processed",
"analysis": {
"faceDetection": {
"facePresent": 0.98,
"multipleFaces": 0.01,
"noFace": 0.01
},
"suspiciousActivity": {
"phoneUsage": 0.02,
"lookingAway": 0.05,
"talking": 0.10
}
}
}When submitting exam data, you can use either multipart/form-data or JSON format depending on your needs.
Use this format when you need to upload binary files (webcam and screen recordings) along with JSON data.
POST {YOUR_API_BASE_URL}/exams/{exam_id}/submit
Content-Type: multipart/form-data
Fields:
- stats: JSON string (session data)
- warnings: JSON string (activity logs)
- webcam: Binary file (WebM/MP4)
- screen: Binary file (WebM/MP4)
Response: 200 OK (JSON)Use this format when you prefer to send all data as JSON, including Base64-encoded video files.
POST {YOUR_API_BASE_URL}/exams/{exam_id}/submit
Content-Type: application/json
{
"stats": {
// Session data (recording duration, clicks, etc.)
"duration": 3600,
"startTime": "2025-03-26T14:30:00Z",
"endTime": "2025-03-26T15:30:00Z",
"browserInfo": {
"userAgent": "Mozilla/5.0...",
"platform": "MacOS"
}
},
"warnings": [
// Array of activity logs
{
"timestamp": "2025-03-26T14:35:22Z",
"type": "tab_switch",
"details": "User switched to another tab"
}
],
"webcam": {
"data": "data:video/webm;base64,..." // Base64 encoded video
"filename": "webcam-recording-timestamp.webm",
"mimeType": "video/webm"
},
"screen": {
"data": "data:video/webm;base64,..." // Base64 encoded video
"filename": "screen-recording-timestamp.webm",
"mimeType": "video/webm"
}
}
Response: 200 OK (JSON)The ProctorAI API uses conventional HTTP response codes to indicate the success or failure of an API request.
| Code | Description |
|---|---|
| 200 - OK | The request was successful |
| 400 - Bad Request | The request was invalid or cannot be served |
| 401 - Unauthorized | Authentication failed or user doesn't have permissions |
| 404 - Not Found | The requested resource could not be found |
| 429 - Too Many Requests | Rate limit exceeded |
| 500 - Server Error | Something went wrong on our end |
{
"error": {
"code": "invalid_request",
"message": "The request was invalid",
"details": [
{
"field": "webcam",
"issue": "File size exceeds the maximum allowed (100MB)"
}
]
}
}Rate limiting is not currently implemented in the ProctorAI API by default. Since you are hosting the API on your own server infrastructure, you have the flexibility to implement rate limiting according to your specific needs and requirements.
If you wish to implement rate limiting for your ProctorAI API instance, we recommend considering factors such as:
In future releases, we may provide sample code and guidance for implementing rate limiting in various server environments. If you need assistance with implementing rate limiting for your specific use case, please contact our support team.
Stay tuned for our SDKs and libraries.