Create a test and run it in TestWatch

How it works

1. Request an API key with the form. We send your organization_id and key when the account is ready.
2. Your backend creates a test (assessment + exam URL + proctoring options).
3. You share the launch link with students.
4. Students install TestWatch, open the link, complete camera/screen setup, and take the exam. A test instance is created when they start.

1. Create the test

Call this from your server after you have credentials. Do not put the API key in a browser page.

POST https://proctoring.wonksknow.com/api/v1/test-instances/test-url/create
Content-Type: application/json

{
  "organization_id": "YOUR_ORGANIZATION_ID",
  "remote_assessment_id": "exam_101_fall23",
  "created_by": "instructor@yourschool.edu",
  "test_url": "https://your-lms.example.com/exams/101",
  "proctoring_preferences": {
    "screen-video-recording": true,
    "face-tracking": true,
    "browser-visibility": true,
    "multiple-display-check": true,
    "prevent-copy-paste": true,
    "lock-browser": true,
    "secondary-camera-check": false,
    "disable-devtools": false,
    "multiple-voice-detection": false,
    "raisehand-integration": false,
    "adaptive-quality": true,
    "ask-user-details-before-start": false,
    "show-privacy-policy-before-start": false,
    "privacy-policy-url": "",
    "2fa": false,
    "2fa-privacy-url": "",
    "2fa-terms-url": "",
    "2fa-additional-url": "",
    "360-degree-room-view": false,
    "host-test-on-web": false,
    "enable-screen-share": false,
    "enable-video-recording-only": false
  }
}

remote_assessment_id is your exam id (unique per organization). test_url is the page students actually take — TestWatch loads it in an iframe. If you omit test_url, a placeholder launch page is generated.

Proctoring options

2. Add a test taker

After the test exists, add each student from your server. If you omit taker_id, a unique 6-character ID is generated. Send the returned short_url to that student.

POST https://proctoring.wonksknow.com/api/v1/test-instances/takers/create
Content-Type: application/json

{
  "organization_id": "YOUR_ORGANIZATION_ID",
  "remote_assessment_id": "exam_101_fall23",
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "taker_id": "student_45821"
}

The response includes taker_id, a unique short_url (also launch_url) such as https://proctoring.wonksknow.com/s/9QDYLF, and a response_url such as https://proctoring.wonksknow.com/r/9QDYLF. Send the launch link to the student. When they finish a remote exam, POST their answers as JSON to the response URL.

2b. Post answers from a remote exam

If the exam lives on your site (not uploaded into TestWatch), POST JSON to the student’s response_url. TestWatch stores it on that sitting and shows it under View answers on the video report.

POST https://proctoring.wonksknow.com/r/9QDYLF
Content-Type: application/json

{
  "answers": [
    {"id": "q1", "prompt": "What is 2 + 2?", "answer": "4", "expected": "4", "correct": true}
  ],
  "score": 1,
  "total": 1
}

You can also POST a plain object of question IDs to answers, or an array of answers. Same payload is accepted at POST https://proctoring.wonksknow.com/api/v1/test-instances/takers/9QDYLF/answers.

3. Send students the launch link

Use the same remote_assessment_id you registered. To identify the student, add user_id (your LMS or app user id):

https://proctoring.wonksknow.com/api/v1/test-instances/launch?assessment_id=exam_101_fall23&user_id=student_45821

Path form (recommended in TestWatch): https://proctoring.wonksknow.com/api/v1/test-instances/launch/exam_101_fall23/user/student_45821

The launch page loads your stored preferences, then starts TestWatch. On the web it prompts them to open or install the desktop app. Inside TestWatch, the same URL starts camera, screen share, and the exam iframe. A test instance is created per student when user_id is present.

Download TestWatch for Windows or Mac

4. What happens at exam start

1. Student opens the launch link in TestWatch.
2. They confirm camera, microphone, and (if enabled) screen share. Optional second camera is a phone QR flow.
3. The platform creates a test instance for that sitting and starts recording / monitoring.
4. Your exam URL runs in the iframe. Violations post to the assessment report. Video chunks upload during the session and stitch when they finish.

You do not call a separate “create instance” API for each student. Register the test once; instances are created when students launch. Pass user_id on the launch URL (or on POST /api/v1/test-instances/create) so each sitting is tied to that student.