Assessment infrastructure, as an API

Create a proctored, AI-graded sitting with one POST; your candidate gets a personal link; you get the scored result by webhook. The sittings, reports and credentials are identical to those delivered through the AssessAll console.

Authentication

Every request carries an API key in the Authorization header. Keys are created in your workspace under Settings → API keys (the secret is shown once). Sittings require a key that belongs to an organisation and has the write permission.

Authorization: Bearer aa_xxxxxxxxxxxxxxxxxxxxxxxx

Machine-readable spec: /api/v1/openapi.json (OpenAPI 3.1 — feed it to your client generator or your coding agent).

Quickstart — create a sitting

Provide the candidate and exactly one of assessment_id, catalog_entry_id (a paid catalogue item, charged to your credit wallet at your contracted price) or product_id. The response carries the sitting id and the candidate's personal no-login take URL — send it to them however you like; AssessAll also emails it. The optional program_name (≤80 chars) is the heading the candidate sees on their take page.

curl -X POST https://www.assessall.com/api/v1/sittings \
  -H "Authorization: Bearer $ASSESSALL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "candidate": { "email": "priya@example.com", "full_name": "Priya N" },
    "catalog_entry_id": "<entry-uuid>",
    "program_name": "Acme Hiring — Round 1",
    "due_at": "2026-09-30"
  }'

# 201
{
  "ok": true,
  "sitting": {
    "id": "…",
    "status": "assigned",
    "take_url": "https://assessall.com/a/…",
    "candidate": { "id": "…", "email": "priya@example.com", "full_name": "Priya N" },
    "credits_charged": 20
  }
}

An empty wallet answers with the standard envelope — 402 { "wallet_insufficient": true, … } — and creates nothing.

Endpoints

Agent Assessment

Assess an AI agent the way you would a candidate. Create an agent sitting (10 credits), drive your agent through the 20-task loop, and receive a scored profile — five pillars (instruction fidelity, grounded accuracy, judgement & escalation, tool reasoning, communication), a composite, and a band. Fabrication traps and prompt-injection tests are built in; per-task scores are never revealed mid-run.

POST /api/v1/agent-sittings            {"agent": {"name": "support-bot-v3"}}
  -> 201 { sitting: { id, task: { instructions, context, response_format } } }

POST /api/v1/agent-sittings/{id}/respond   {"output": "<your agent's answer>"}
  -> { completed: false, task: <next> }        # repeat until…
  -> { completed: true, scoring: "in_progress" }

GET  /api/v1/agent-sittings/{id}
  -> { sitting: { status: "scored", result: { composite, band, pillars: [...] } } }

webhook: agent_sitting.scored — same signature scheme as sitting.scored

Webhooks

Register an https:// endpoint under Settings → API keys → Webhooks (org admins). Four events: sitting.started (the candidate began), sitting.scored (the result below), credential.issued (a verifiable credential was earned, with its public verify URL), and agent_sitting.scored. The moment a sitting is fully scored, AssessAll POSTs sitting.scored:

POST <your endpoint>
X-AssessAll-Event: sitting.scored
X-AssessAll-Signature: sha256=<hex HMAC-SHA256 of the raw body>

{
  "event": "sitting.scored",
  "created_at": "…",
  "data": {
    "sitting_id": "…",
    "attempt_id": "…",
    "score": 78.4,
    "passed": true,
    "candidate": { "id": "…", "email": "…", "full_name": "…" },
    "assessment": { "product_id": "…", "slug": "…", "title": "…" },
    "links": { "sitting": "https://www.assessall.com/api/v1/sittings/…" }
  }
}

Verify by recomputing the HMAC over the raw request bytes with the signing secret shown when you created the endpoint:

import { createHmac, timingSafeEqual } from "crypto";

function verify(rawBody: string, header: string, secret: string) {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  return timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

Answer with any 2xx within 5 seconds. A network failure or 5xx is retried once; every attempt is visible in the console next to the endpoint.

Errors