AssessAll
Developers · API v1

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.

Public MCP server — the catalogue, for AI agents

AssessAll runs a free, read-only Model Context Protocol server. Any MCP client — Claude, ChatGPT developer mode, Cursor, VS Code, your own agent — can search the public assessment catalogue, read one assessment's description and one-time INR and USD price (the same price checkout charges), list the free practice tests, and search the guides. No key, no account, no personal data.

Endpoint (Streamable HTTP):  https://www.assessall.com/mcp
Server card:                 https://www.assessall.com/mcp/server-card
Registry name:               com.assessall/catalogue

Tools (all read-only):
  search_assessments  { query, max_price_usd?, limit? }
  get_assessment      { slug }
  list_practice_tests {}
  search_guides       { query, limit? }

Claude Code, for example:

claude mcp add --transport http assessall https://www.assessall.com/mcp

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

Method & pathWhat it does
POST /api/v1/sittingsCreate a sitting: provision the candidate, assign, mint the take link, charge credits for paid items.
GET /api/v1/sittingsList sittings created over the API (limit, offset, status filters).
GET /api/v1/sittings/{id}One sitting's status; once scored, the result block carries score, passed and scored_at.
GET /api/v1/assessmentsThe catalogue your key can assign from — public library plus your organisation's own.
GET /api/v1/resultsScored attempts across your organisation's members.
GET /api/v1/badgesVerifiable credentials issued to your organisation's members.

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

401Missing, invalid or expired API key.
402wallet_insufficient — the sitting would cost more credits than the wallet holds. Nothing was created.
403The key lacks the permission (write for POST) or is not organisation-linked.
404Unknown sitting id — including ids that belong to another organisation.
409The candidate account exists but is deactivated.

Building something bigger?

Volume pricing, custom assessments, white-label delivery and agent-assessment pilots: partners@assessall.com.