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/mcpAuthentication
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_xxxxxxxxxxxxxxxxxxxxxxxxMachine-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 & path | What it does |
|---|---|
POST /api/v1/sittings | Create a sitting: provision the candidate, assign, mint the take link, charge credits for paid items. |
GET /api/v1/sittings | List 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/assessments | The catalogue your key can assign from — public library plus your organisation's own. |
GET /api/v1/results | Scored attempts across your organisation's members. |
GET /api/v1/badges | Verifiable 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.scoredWebhooks
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
| 401 | Missing, invalid or expired API key. |
| 402 | wallet_insufficient — the sitting would cost more credits than the wallet holds. Nothing was created. |
| 403 | The key lacks the permission (write for POST) or is not organisation-linked. |
| 404 | Unknown sitting id — including ids that belong to another organisation. |
| 409 | The candidate account exists but is deactivated. |
Building something bigger?
Volume pricing, custom assessments, white-label delivery and agent-assessment pilots: partners@assessall.com.