Read your assessment results from your own software, and get a message the moment someone starts, submits, is graded or gets a decision.
The API lets your software pull results out of AlgoArena: your applicant tracking system, a spreadsheet, a data warehouse or a script. Webhooks work the other way. We send your system a signed message as soon as something happens, so you do not have to keep asking. With webhooks you can also connect Zapier and, through it, Slack or email.
Owners and admins set both up in Settings, API and webhooks in the assessment workspace. Each key and each webhook belongs to one workspace and only ever sees that workspace's results.
A result has the participant's name and email, status and times, points, the five skill scores and AI fluency, integrity flags, the decision, and a link to the full report, which needs a sign-in. The API and webhooks never send code, AI chats, replays, webcam or ID photos, notes, or the rating a participant gives us. On a training assessment they send a level for each skill instead of the numbers, the same as the report.
Make a key in Settings, API and webhooks. We show it once. We store only a fingerprint of it, so we cannot show it again. Send it on every request:
Authorization: Bearer aa_live_...A key acts for the whole workspace and can read every result in it. Keep it on your server, never in a web page or an app. If a key leaks, revoke it in settings. It stops working on the next request. A key keeps working when the person who made it leaves the team, until someone revokes it, and stops when the workspace is deleted.
Base URL: https://algoarena.net/api/v1. Every reply is JSON. Times are ISO 8601 in UTC. The full machine-readable list is in openapi.json.
GET /api/v1/assessments returns your workspace's assessments, newest first. Deleted ones are left out. Each has id, title, status (draft, active or archived), mode (hiring, training or hackathon), created_at, time_limit_minutes and pass_mark_percent.
curl https://algoarena.net/api/v1/assessments \
-H "Authorization: Bearer $ALGOARENA_API_KEY"GET /api/v1/results returns results, one per attempt. Without updated_since, the newest submission comes first, and attempts still in progress come after every submitted one.
| Query | What it does |
|---|---|
| assessment_id | Only this assessment's results. |
| status | in_progress, submitted or expired (closed without being submitted). |
| updated_since | Only results that changed at or after this time, oldest change first. A result changes when it is submitted, graded, gets a decision or is closed. Store the last updated_at you saw and ask again from there. Attempts still in progress are not included until they change. |
| limit | 1 to 100. Default 50. |
| cursor | The next_cursor from the page before. |
curl "https://algoarena.net/api/v1/results?status=submitted&limit=20" \
-H "Authorization: Bearer $ALGOARENA_API_KEY"
# Everything that changed since your last sync, oldest change first
curl "https://algoarena.net/api/v1/results?updated_since=2026-11-01T00:00:00Z" \
-H "Authorization: Bearer $ALGOARENA_API_KEY"
# The next page
curl "https://algoarena.net/api/v1/results?cursor=NEXT_CURSOR_FROM_THE_LAST_PAGE" \
-H "Authorization: Bearer $ALGOARENA_API_KEY"GET /api/v1/results/{id} returns one result. A result from another workspace, or a preview run, is a 404.
curl https://algoarena.net/api/v1/results/RESULT_ID \
-H "Authorization: Bearer $ALGOARENA_API_KEY"The API, every webhook and every page of results send this same shape.
{
"object": "result",
"id": "Xk2f9QpL7mWc3Rt8",
"assessment": { "id": "a81Jd02kQm", "title": "Backend engineer", "mode": "hiring" },
"participant": { "name": "Ada Lovelace", "email": "ada@example.com" },
"status": "submitted",
"started_at": "2026-11-03T15:02:11.000Z",
"submitted_at": "2026-11-03T15:58:40.000Z",
"updated_at": "2026-11-03T16:01:05.000Z",
"grading_status": "ready",
"points": { "score": 82, "max": 100, "percent": 82 },
"pass_mark": { "percent": 70, "result": "passed" },
"ai_fluency": {
"overall": { "score": 74, "level": null },
"skills": {
"problem_solving": { "score": 82, "level": null },
"planning": { "score": 66, "level": null },
"prompting": { "score": 77, "level": null },
"verification": { "score": 71, "level": null },
"agentic_workflow": { "score": 80, "level": null }
},
"scores_withheld": false
},
"integrity": {
"status": "flags_for_review",
"flags": [{ "id": "integrity:tab-switch", "type": "integrity", "label": "Switched tabs 14 times" }]
},
"decision": "advance",
"report_url": "https://algoarena.net/recruiting/assessment/a81Jd02kQm/candidate/Xk2f9QpL7mWc3Rt8"
}| Field | Meaning |
|---|---|
| status | in_progress, submitted or expired. |
| grading_status | not_submitted, grading, ready (every score is final) or unavailable (grading could not finish; someone on your team can re-run it from the report). Scores are null until it is ready. |
| points | The points earned, the most there were, and the percent. |
| pass_mark | Your own pass mark and whether the points reached it (passed or failed). Null when you did not set one. |
| ai_fluency.skills | Problem solving, planning, prompting, verification and agentic workflow, each 0 to 100. Null means not measured, for example AI was not allowed on the questions. It does not mean 0. |
| ai_fluency.overall | The AI fluency score, from the AI skills that were measured. Null means not measured. |
| ai_fluency.scores_withheld | True on a training assessment. Then every score is null and level is novice, emerging, average, above_average or expert. |
| integrity | pending until the attempt is submitted, then no_flags or flags_for_review with the flags. A flag is an automatic signal for a person to check in the replay. It is not proof of anything and changes no score. |
| decision | advance, needs_discussion, do_not_advance or not_decided. Set by your team. AlgoArena never makes this call. |
| report_url | The full report. Opening it needs a sign-in to your workspace. |
Lists come back as data, has_more and next_cursor. To get the next page, send the same query with cursor set to next_cursor. Keep going while has_more is true. A page can hold fewer results than limit even when more exist, so check has_more, not the count.
{
"object": "list",
"data": [ { "object": "result", "id": "Xk2f9QpL7mWc3Rt8", "...": "..." } ],
"has_more": true,
"next_cursor": "eyJtIjoic3VibWl0dGVkIiwidCI6WzE3NjIxODU1MjAsMF0sImlkIjoiWGsyZjlRcEw3bVdjM1J0OCJ9"
}Each key can make 120 requests a minute. Every reply has X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Past the limit you get a 429 with Retry-After in seconds.
An error is JSON with error (a sentence) and code (stable, for your code to check).
| Status | When |
|---|---|
| 400 | A bad query value (invalid_parameter) or a cursor from a different query (invalid_cursor). |
| 401 | No key (missing_api_key), a wrong key (invalid_api_key), a revoked key (api_key_revoked), or the workspace was deleted (workspace_deleted). |
| 404 | Not in your workspace (not_found). |
| 429 | Too many requests (rate_limited). |
| 500 | Our fault (internal_error). Try again. |
In Settings, API and webhooks, add your endpoint's URL and pick its events. We show its signing secret once. The URL must be public HTTPS on the standard port. Addresses inside private networks are refused.
| Event | When we send it |
|---|---|
| participant.started | Someone started an assessment. |
| participant.submitted | Someone submitted, or their time ran out and the attempt was submitted for them. |
| result.graded | Grading finished and the scores are final. Sent again if a score changes later. |
| decision.made | Someone on your team recorded or changed the decision. |
| webhook.test | Only from the Send test event button. Its result is clearly fake and it has "test": true. |
Every event is a POST with a JSON body: the event id, its type, when it happened, your workspace id and the result as it was when we sent it.
POST /your-endpoint HTTP/1.1
Content-Type: application/json
User-Agent: AlgoArena-Webhooks/1.0 (+https://algoarena.net/documentation/api)
X-AlgoArena-Event: result.graded
X-AlgoArena-Event-Id: evt_3f1c0b8e9d2a4c6b8e0f1a2b3c4d5e6f
X-AlgoArena-Timestamp: 1762185665
X-AlgoArena-Signature: v1=5d1f0c...e9a2
{
"id": "evt_3f1c0b8e9d2a4c6b8e0f1a2b3c4d5e6f",
"type": "result.graded",
"created_at": "2026-11-03T16:01:05.000Z",
"workspace_id": "your-workspace-id",
"data": { "result": { "object": "result", "id": "Xk2f9QpL7mWc3Rt8", "...": "..." } }
}Reply with any 2xx status within 10 seconds. Do slow work after you reply. We do not follow redirects, so give the final URL. Events can arrive out of order, and the same event can arrive twice, so use id to skip ones you already handled, and the result's updated_at to keep the newest.
In Zapier, start a Zap with Webhooks by Zapier, Catch Hook, paste its URL as your endpoint, and press Send test event so Zapier can see every field. Slack needs its own message format, so send events to Slack through Zapier, Make or your own code rather than pasting a Slack URL here.
Check every webhook before you trust it. We sign timestamp + "." + raw body with HMAC-SHA256, using your signing secret (the whole whsec_... text) as the key, and send v1= and the hex digest in X-AlgoArena-Signature. The timestamp, in Unix seconds, is in X-AlgoArena-Timestamp. To check:
import crypto from "node:crypto"
import express from "express"
const app = express()
const SECRET = process.env.ALGOARENA_WEBHOOK_SECRET // whsec_...
// Read the raw body. Parsing the JSON first and turning it back into text
// changes the bytes, and the signature will not match.
app.post("/algoarena-webhook", express.raw({ type: "application/json" }), (req, res) => {
const timestamp = req.get("X-AlgoArena-Timestamp") || ""
const signature = req.get("X-AlgoArena-Signature") || ""
const body = req.body.toString("utf8")
const expected =
"v1=" + crypto.createHmac("sha256", SECRET).update(timestamp + "." + body).digest("hex")
const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300
const same =
signature.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
if (!fresh || !same) return res.status(400).send("Bad signature")
const event = JSON.parse(body)
// Skip events you already handled: the same event can arrive twice.
// if (alreadySeen(event.id)) return res.sendStatus(200)
console.log(event.type, event.data.result?.id)
res.sendStatus(200)
})
app.listen(3000)import hashlib
import hmac
import json
import os
import time
from flask import Flask, abort, request
app = Flask(__name__)
SECRET = os.environ["ALGOARENA_WEBHOOK_SECRET"].encode() # whsec_...
@app.post("/algoarena-webhook")
def algoarena_webhook():
timestamp = request.headers.get("X-AlgoArena-Timestamp", "")
signature = request.headers.get("X-AlgoArena-Signature", "")
body = request.get_data() # the raw bytes, before any JSON parsing
if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300:
abort(400)
expected = "v1=" + hmac.new(SECRET, timestamp.encode() + b"." + body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(signature, expected):
abort(400)
event = json.loads(body)
print(event["type"], (event["data"]["result"] or {}).get("id"))
return "", 200If your endpoint does not reply 2xx in time, we try again 5 minutes later, then after 1 hour, 6 hours and 16 hours: 5 tries over about a day. After that the delivery is marked failed. A test event is tried once.
Each endpoint shows its last 50 deliveries in settings: the event, whether it was delivered, your endpoint's reply code, how many tries it took and when the next try is. You can turn an endpoint off without deleting it. Events that happen while it is off are not sent later.
Questions, or something you need that is not here? Email contact@algoarena.net.