AlgoArena docs

API and webhooks

Read your assessment results from your own software, and get a message the moment someone starts, submits, is graded or gets a decision.

Overview

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.

Authentication

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.

Endpoints

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.

List assessments

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"

List results

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.

QueryWhat it does
assessment_idOnly this assessment's results.
statusin_progress, submitted or expired (closed without being submitted).
updated_sinceOnly 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.
limit1 to 100. Default 50.
cursorThe 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 one result

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 result object

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"
}
FieldMeaning
statusin_progress, submitted or expired.
grading_statusnot_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.
pointsThe points earned, the most there were, and the percent.
pass_markYour own pass mark and whether the points reached it (passed or failed). Null when you did not set one.
ai_fluency.skillsProblem 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.overallThe AI fluency score, from the AI skills that were measured. Null means not measured.
ai_fluency.scores_withheldTrue on a training assessment. Then every score is null and level is novice, emerging, average, above_average or expert.
integritypending 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.
decisionadvance, needs_discussion, do_not_advance or not_decided. Set by your team. AlgoArena never makes this call.
report_urlThe full report. Opening it needs a sign-in to your workspace.

Pages and limits

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.

Errors

An error is JSON with error (a sentence) and code (stable, for your code to check).

StatusWhen
400A bad query value (invalid_parameter) or a cursor from a different query (invalid_cursor).
401No key (missing_api_key), a wrong key (invalid_api_key), a revoked key (api_key_revoked), or the workspace was deleted (workspace_deleted).
404Not in your workspace (not_found).
429Too many requests (rate_limited).
500Our fault (internal_error). Try again.

Webhooks

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.

EventWhen we send it
participant.startedSomeone started an assessment.
participant.submittedSomeone submitted, or their time ran out and the attempt was submitted for them.
result.gradedGrading finished and the scores are final. Sent again if a score changes later.
decision.madeSomeone on your team recorded or changed the decision.
webhook.testOnly 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.

Zapier and Slack

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.

Checking signatures

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:

  1. Read the raw body as it arrived, before parsing the JSON.
  2. Refuse it if the timestamp is more than 5 minutes from now. This stops an old message being sent again.
  3. Compute the HMAC of the timestamp, a dot, and the raw body, and compare it with the header in constant time.

Node.js

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)

Python

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 "", 200

Retries and the log

If 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.