API reference

The API is a Hono app (apps/api/src/app.ts) mounted at /api. Every route except GET /api/health requires an identity (see Authentication and authorisation). Request bodies are JSON, validated with zod schemas from packages/core/src/schemas.ts, and size-capped while streaming (256 KB unless noted). Route IDs must be UUIDs. Response types are exported from @workbench/core and used by the web client (apps/web/src/lib/api.ts).

Errors are JSON: { "error": "<code>", "message": "…" }, plus issues for validation_error.

Status	Code examples
400	bad_request (including a value the database refuses: a check violation or numeric overflow), validation_error, attribute_identifies_people, invalid_json, invalid_reference_data, invalid_prompt, unknown_occupation
401	unauthenticated
403	forbidden, not_provisioned, deactivated
404	not_found
409	conflict, pii_unavailable
413	payload_too_large
429	ai_budget_exceeded
503	ai_unavailable, pii_unconfigured

Platform

Method and path	Who	Notes
GET /api/health	Anyone	{ ok, version, environment }. Unauthenticated.
GET /api/me	Signed in	The user, environment, aiEnabled and sign-in mode.
GET /api/users	Signed in	Active users (admins also see deactivated), for team pickers.
POST /api/users	Admin	Add a user. Audits user_created.
PATCH /api/users/:id	Admin	Role, active, name. Refuses to remove the last active admin. Audits user_updated.
GET /api/clients	Signed in	All clients.
POST /api/clients	Signed in	Audits client_created.
PATCH /api/clients/:id	Creator or admin	Name, sector, notes, archived. Audits client_updated. (No UI yet.)
GET /api/clients/:id/brand	Signed in	The client's deliverable brand (or null) and whether the caller may change it.
PUT /api/clients/:id/brand	Admin, the client's creator or a lead of one of its engagements	Logo, colours, font; refused if the primary can't carry white text or an SVG logo has active content. Audits client_brand_updated.
DELETE /api/clients/:id/brand	As above	Audits client_brand_removed.
GET /api/benchmarks?datasetId=	Signed in	Cross-engagement medians; the optional dataset's engagement is excluded.

Engagements

Method and path	Who	Notes
GET /api/engagements	Signed in	Engagements the user can read, with their role and PII flag.
POST /api/engagements	Signed in	Creates the engagement (with a wrapped identity key when a KEK is configured) and adds the creator as lead with PII access. Audits engagement_created, member_added.
GET /api/engagements/:id	Member
PATCH /api/engagements/:id	Lead	Name, pack, region, sharing flags, retention, and reportNotes ({ sections, valueConcentration?, terms }, reportNotesSchema; null or empty notes clear them; a swap's from needs a letter and may not contain digits, £, $, € or %). reportNotes is refused with 409 conflict unless the engagement is active; a purge clears it. Changes only the fields sent. A pack change rescores the engagement's datasets. Audits engagement_updated, recording reportNotes as updated or cleared, never the text.
POST /api/engagements/:id/close	Lead	Audits engagement_closed.
POST /api/engagements/:id/reopen	Lead	Closed only. Audits engagement_reopened.
POST /api/engagements/:id/purge	Lead	Body { confirm } must equal the name. Closed only. Audits engagement_purged.
DELETE /api/engagements/:id	Admin	Audits engagement_deleted.
GET /api/engagements/:id/members	Member
PUT /api/engagements/:id/members	Lead	Add or update { email, role, piiAccess }. Keeps at least one lead. Nobody may switch on their own PII access (403, admins included); keeping or dropping it is fine. Audits member_added / member_updated.
DELETE /api/engagements/:id/members/:userId	Lead	Keeps at least one lead. Audits member_removed.
GET /api/engagements/:id/overrides	Member
PUT /api/engagements/:id/overrides	Lead, analyst	Checked against the current reference version; applied and re-scored in every dataset holding the title. Audits override_set.
DELETE /api/engagements/:id/overrides?title=	Lead, analyst	Re-classifies without AI and re-scores. Audits override_removed.
GET /api/engagements/:id/datasets	Member
POST /api/engagements/:id/datasets	Lead, analyst	Creates a dataset pinned to the current reference version. withIdentities needs PII access. useAi (default true) is stored as the dataset's AI choice. Audits dataset_created.
GET /api/engagements/:id/audit?offset=&limit=	Lead	The engagement's trail, 100 a page by default.

Datasets

Method and path	Who	Notes
GET /api/datasets/:id	Member	Detail, summary, settings, mapping, progress and latestReferenceVersion.
PATCH /api/datasets/:id	Lead, analyst	Rename, or save settings (re-scores). Audits dataset_renamed / dataset_rescored.
POST /api/datasets/:id/reference	Lead, analyst	{ version? }: rescore onto a published reference version (the newest by default). Audits dataset_reference_changed.
DELETE /api/datasets/:id	Lead, analyst	Audits dataset_deleted.
POST /api/datasets/:id/rows	Lead, analyst	{ chunk, rows, identities? }: up to 2,000 rows; 6 MB. employeeId and managerEmployeeId may not contain an @ (after NFKC): an email is never stored as an ID, and the whole chunk is refused with validation_error. Each row (employeeRowSchema) may carry fte (0–1, stored to two decimal places; absent, or a value that rounds to 0, means unknown and counts as 1) and attributes (up to five label → value groupings, headings distinct after trimming; the whole chunk is refused with validation_error if any heading or value looks like personal data, as attributesProblem judges). Idempotent per chunk number. Identities need PII access; audits identities_uploaded.
POST /api/datasets/:id/complete	Lead, analyst	Checks each extra grouping's variety (attributeVarietyProblem): one that would identify people is refused with 400 attribute_identifies_people, and the dataset stays uploading (delete it and upload again without that column). Otherwise extracts distinct titles; status becomes classifying. Audits dataset_uploaded.
POST /api/datasets/:id/classify	Lead, analyst	{ useAi? }: resolves up to 600 pending titles; finalises when none remain. Returns progress. Omitted useAi uses the dataset's stored choice; useAi can switch AI off for the call but never on for a dataset created with useAi: false.
GET /api/datasets/:id/rows?offset=&limit=	Member	Rows in upload order, up to 10,000 a page.
GET /api/datasets/:id/titles	Member	Each title's classification and reviewRequired.
POST /api/datasets/:id/identities/reveal	PII access	{ purpose, employeeIds? }; 4 MB. Audits identities_revealed.
POST /api/datasets/:id/identities/match	PII access	{ emails, purpose }; 8 MB. Returns matches by index, never the emails. Audits identities_matched.
POST /api/datasets/:id/exports	Member	{ kind, artefact, named }: the browser records an export it generated. Audits export_generated.
GET /api/datasets/:id/ai/:kind	Member	exec-summary or lifecycle: the cached AI version, or a rule-based one computed on the fly. Never spends tokens.
POST /api/datasets/:id/ai/:kind	Lead, analyst	Generates with AI (or explains why not) and caches. Audits ai_generated.
POST /api/datasets/:id/ai/ask	Member	{ question } (3–1,000 characters). 429/503 when AI is unavailable. Audits ai_generated.
GET /api/datasets/:id/copilot-plans	Member
POST /api/datasets/:id/copilot-plans	Lead, analyst	{ name, config }; 4 MB. Audits copilot_plan_saved.
GET /api/copilot-plans/:id	Member
PUT /api/copilot-plans/:id	Lead, analyst	Audits copilot_plan_saved.
DELETE /api/copilot-plans/:id	Lead, analyst	Audits copilot_plan_deleted.

Export auditing is reported by the browser

Deliverables are generated in the browser, so the server learns of an export when the client calls POST /datasets/:id/exports afterwards. The call is fire-and-forget; the audit entry records what the client reports. Identity reveals, by contrast, are audited by the server as they happen.

Reference data

Method and path	Who	Notes
GET /api/reference	Signed in	{ version, publishedAt, notes } of the live version.
GET /api/reference/versions/:version	Signed in	A published version's full data (drafts only for admins, under RLS).
GET /api/admin/reference	Admin	{ current, draft, versions } (metadata, no data).
POST /api/admin/reference/draft	Admin	{ basedOn? }: start the draft. 409 if one exists. Audits reference_draft_created.
GET /api/admin/reference/draft	Admin	{ draft } with data and live validation issues, or null.
PUT /api/admin/reference/draft	Admin	{ data } or { section, value } or { notes }; 4 MB. Shape errors refuse the save.
POST /api/admin/reference/draft/publish	Admin	{ notes } (3–2,000 characters). Refused while there are errors. Audits reference_published.
DELETE /api/admin/reference/draft	Admin	Audits reference_draft_discarded.

Prompts

Method and path	Who	Notes
GET /api/admin/prompts	Admin	Each prompt's label, purpose, live version and draft.
GET /api/admin/prompts/datasets	Admin	Up to 200 ready datasets across all engagements, for tests.
GET /api/admin/prompts/:key	Admin	The definition (variables, output contract) and every version.
POST /api/admin/prompts/:key/draft	Admin	{ from? }. Audits prompt_draft_created.
PUT /api/admin/prompts/:key/draft	Admin	Partial template and notes; 128 KB. Returns the draft and its issues.
POST /api/admin/prompts/:key/draft/publish	Admin	{ notes }. Refused while validatePrompt reports issues. Audits prompt_published.
DELETE /api/admin/prompts/:key/draft	Admin	Audits prompt_draft_discarded.
POST /api/admin/prompts/:key/test	Admin	{ version, titles?, industry?, region?, datasetId?, question?, dryRun }. Metered unless a dry run. Audits prompt_tested.

Administration

Method and path	Who	Notes
GET /api/admin/stats	Admin	Engagements, datasets, people analysed, cache entries and verified.
GET /api/admin/cache?q=&offset=&limit=	Admin	Most-used first.
PATCH /api/admin/cache	Admin	{ normalisedTitle, context, verified }. Audits cache_entry_verified.
DELETE /api/admin/cache	Admin	{ normalisedTitle, context }. Audits cache_entry_deleted.
GET /api/admin/audit?offset=&limit=&action=	Admin	The platform trail, with engagement names. action filters by action code (not exposed in the UI).
GET /api/admin/ai-usage	Admin	Twelve months by month and feature, month-to-date spend, budget and model.