Pulling results, transcripts and recordings by API

The Results API is a read-only, versioned HTTP API. It answers the question an institution asks after the interviews are done: for each student, what was the outcome, what was said, and, if policy allows, what did it sound like. It is the same data the report shows, in JSON, so a badge platform or a records system can keep its own copy without anyone clicking Export.

1. 1

   Open Settings, then API access, and create a key. Name it after the system that will use it and choose what it may read: results always, transcripts and recordings only if that system needs them. The key is shown once; copy it into that system right away.

2. 2

   Send the key as a bearer token on every request: Authorization: Bearer viva_sk_… Test it with GET https://www.vivaproof.com/api/v1/me, which returns the key name, its scopes and how many classes it reaches.

3. 3

   List assignments with GET /api/v1/assignments, then pull GET /api/v1/assignments/{id}/results. Each row is one interview session: the student, status, integrity verdict, scores or criteria outcomes, the instructor grade, and links to the transcript and recording when your key may read them.

4. 4

   Poll cheaply with completed_since=<ISO time>: only sessions completed at or after that moment come back. Pages carry next_cursor; pass it back as cursor until it is null.

What a result looks like

One shape for both rubric styles. With a Met / Not yet rubric, rubric.mode is "competency" and every criterion carries outcome (met, not_yet or not_assessed), confidence, and the evidence Viva cited; an instructor decision replaces the outcome and names who decided. With a points rubric, criteria carry awarded and maximum points and a suggested grade, and scores carry the effective overall, which is the instructor override when there is one. An abandoned session has status "abandoned" and no scores. Nothing is ever reported as a zero that was not graded.

• GET /api/v1/sessions/{id} returns one result with the transcript inline when the key may read transcripts. GET /api/v1/sessions/{id}/transcript returns the turns as JSON, or plain text with format=text.
• GET /api/v1/sessions/{id}/recording redirects to a link that plays the interview audio for ten minutes, then expires. It needs a key created with Recordings turned on. Every recording read is written to the request log under Settings, so you can always see what left.
• A personal key reaches the classes you own, co-teach, assist or grade. A school admin can create a school-wide key that reaches every class of the school.
• Keys are rate limited to 120 requests a minute. Revoking a key stops it immediately and keeps its history.