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, and the code editor with test cases for coding 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.org/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.org/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, or one of your custom interviews (with custom: true)
custom	Set true when interviewId is a custom interview you created (section 5)
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
resume	Optional { "text": "...", "name": "..." } — the candidate's resume text; the interviewer tailors its questions to it

Response:

{
  "status": "success",
  "session": { "_id": "44s2rmqbh", "interviewId": "dsa-1", "status": "active" },
  "embedUrl": "https://onecompiler.org/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.org/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 a spoken conversation
(everything else). 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.org/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 }]
    }
  }
}

6. Author your own interviews

You're not limited to the catalogue — create custom interviews with your own
role, topics, and interviewer playbook, then run sessions against them with
custom: true. The brief is private: it steers the AI interviewer and is
never shown to candidates.

curl --request POST 'https://onecompiler.org/v1/ai-interviewer/interviews' \
--header 'X-API-Key: your_api_key' \
--header 'X-User-Token: users_api_token' \
--header 'Content-Type: application/json' \
--data '{
    "title": "Backend engineer screen — payments team",
    "kind": "talk",
    "level": "Medium",
    "mins": 30,
    "skills": ["APIs", "SQL", "Debugging"],
    "blurb": "A screening round for backend candidates.",
    "brief": "Interview for a mid-level backend role on a payments team. Cover REST API design, one SQL question on joins, and a debugging scenario with a failing webhook. Probe for reasoning, not memorized answers.",
    "status": "published"
}'

The response returns the interview with its _id. Create sessions against it
exactly like catalogue interviews, adding custom: true:

curl --request POST 'https://onecompiler.org/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": "44xkq2m1p", "custom": true, "personaId": "alex" }'

For "kind": "code" include a problem object (language, title, body,
optional examples and starterCode) — the candidate gets the live editor.

Manage and score them with the rest of the surface:

Endpoint	Description
GET /v1/ai-interviewer/interviews	List your custom interviews
GET /v1/ai-interviewer/interviews/:id	Read one (includes the private brief)
PUT /v1/ai-interviewer/interviews/:id	Update any field, e.g. {"status": "draft"} to unpublish
DELETE /v1/ai-interviewer/interviews/:id	Delete (past sessions keep their reports)
GET /v1/ai-interviewer/interviews/:id/results	Every session taken against it, with taker name, status and score