AI practice interviews can run inside your own product. You keep your own screens
for browsing and picking interviews — our catalogue is available as an API — and
when a user starts one, you create the session server-side and open the interview
room in an iFrame. The room handles everything live: the interviewer's voice,
speech recognition, the code editor with test cases, and the whiteboard for
system-design interviews.

This API uses the enterprise user model: you sync your application users with
POST /v1/users and authenticate them with their userApiToken. If you
haven't set that up yet, start with the Enterprise APIs section.

1. Read the interview catalogue

Render the catalogue however fits your product — your own cards, your own
filters. The response contains the tracks, the interviews per track, and the
interviewer personas.

curl 'https://onecompiler.com/v1/ai-interviewer/catalogue' \
--header 'X-API-Key: your_api_key'

Response (truncated):

{
  "status": "success",
  "personas": [ { "id": "maya", "name": "Maya", "title": "Supportive coach" } ],
  "tracks": [ { "id": "dsa", "cat": "technical", "name": "DSA / Problem solving" } ],
  "interviews": {
    "dsa": [
      {
        "id": "dsa-1",
        "title": "Arrays & hashing warm-up",
        "level": "Easy",
        "mins": 25,
        "kind": "code",
        "skills": ["Hash maps", "Two pointers"],
        "blurb": "Two classic problems with follow-ups on complexity.",
        "hasProblem": true
      }
    ]
  }
}

Interviews with "grades" (the K12 subjects) need a grade when the session is
created — show your user a grade picker first.

2. Create a session for your user

Call this from your backend when the user hits start. X-User-Token is the
api.token of the user copy you created via POST /v1/users.

curl --request POST 'https://onecompiler.com/v1/ai-interviewer/sessions' \
--header 'X-API-Key: your_api_key' \
--header 'X-User-Token: users_api_token' \
--header 'Content-Type: application/json' \
--data '{
    "interviewId": "dsa-1",
    "personaId": "maya",
    "mode": "voice"
}'

Body field	Description
interviewId	Required — an interview id from the catalogue
personaId	maya (supportive coach), alex (neutral professional) or leo (bar raiser). Defaults to maya
mode	voice or chat. Defaults to voice
grade	Required for grade-adaptive interviews, e.g. "Grade 6" — one of the interview's grades

Response:

{
  "status": "success",
  "session": { "_id": "44s2rmqbh", "interviewId": "dsa-1", "status": "active" },
  "embedUrl": "https://onecompiler.com/embed/ai-interviewer/44s2rmqbh"
}

Each session created consumes credits and counts toward the user's daily
interview quota (set by the plan you assign via PUT /v1/users/plan).

3. Embed the interview room

Open the room in an iFrame with the user's token. The allow attribute matters:
the room needs the microphone for voice answers and autoplay for the
interviewer's voice.

<iframe
  frameBorder="0"
  height="100%"
  width="100%"
  allow="microphone; autoplay"
  allowFullScreen
  src="https://onecompiler.com/embed/ai-interviewer/44s2rmqbh?userApiToken=users_api_token&interviewEvents=true"
></iframe>

Query Parameter	Description
userApiToken	Required — the same user token the session was created for
apiKey	Your API account key (optional)
interviewEvents=true	Post interview lifecycle events to the parent window

The room runs the full interview: a short voice introduction, then the live
code editor with test cases (coding interviews) or the whiteboard
(system-design interviews). When the user finishes, the room shows their score
and a short verdict — your application owns everything after that.

4. Capture interview events

With interviewEvents=true, the room posts messages to the parent window:

<script>
    window.onmessage = function (e) {
        if (e.data && e.data.source === "oc-interview") {
            console.log(e.data);
            // { source: "oc-interview", action: "interviewFinished",
            //   sessionId: "44s2rmqbh", score: 78 }
        }
    };
</script>

Action	When
interviewLoaded	The room is ready and the session has started
interviewFinished	The user ended the interview and the report is ready (includes score)
interviewAlreadyCompleted	The session in the URL was already finished

5. Read the results

Pull the full report server-side once you receive interviewFinished (or by
polling). The response includes the overall score, verdict, strengths,
improvements, per-skill scores, and question-by-question feedback.

curl 'https://onecompiler.com/v1/ai-interviewer/sessions/44s2rmqbh' \
--header 'X-API-Key: your_api_key' \
--header 'X-User-Token: users_api_token'

Response (truncated):

{
  "status": "success",
  "session": {
    "_id": "44s2rmqbh",
    "status": "completed",
    "score": 78,
    "feedback": {
      "score": 78,
      "verdict": "Strong problem solving; tighten complexity analysis.",
      "strengths": ["..."],
      "improvements": ["..."],
      "skills": [{ "name": "Hash maps", "score": 82 }],
      "questions": [{ "q": "...", "answer": "...", "score": 80 }]
    }
  }
}