Handbook API
Overview
The Handbook API has three active surfaces:
- Runtime/domain API: generated Mastra routes for Handbook workflows, tools, agents, and discovery.
- Admin UI BFF API: dashboard routes for RAG preparation, PDF jobs, product checks, policy-review orchestration, reviewer actions, and quality feedback.
- Focused Handbook app API: compliance runs, handbook/district libraries, reviewer assistance, and generated document artifacts under the standalone app's
/api/*routes.
Browser code calls /api/admin/handbook/*. The Admin UI server rewrites that to the BFF mount. Local operator calls use /admin-api/admin/handbook/*; testing APIM calls use /dashboard/admin-api/admin/handbook/*.
Runtime Domain Routes
Runtime route generation exposes registered Handbook workflows, tools, agents, and route discovery.
| Method | Path | Purpose |
|---|---|---|
GET | /handbook/routes.json | Discover generated Handbook tool, agent, and workflow routes for the active runtime target. |
POST | /handbook/workflows/{workflowSlug} | Execute a registered workflow synchronously. |
POST | /handbook/workflows/{workflowSlug}/start-async | Start a registered workflow in the background and return a run ID. |
POST | /handbook/workflows/{workflowSlug}/create-run | Create a run for a registered Handbook workflow. |
POST | /handbook/workflows/{workflowSlug}/start | Start a registered Handbook workflow run. |
GET | /handbook/workflows/{workflowSlug}/runs/{runId} | Read a registered Handbook workflow run status/result. |
POST | /handbook/tools/{toolSlug} | Execute a registered Handbook tool with flat JSON input. |
POST | /handbook/agents/{agentSlug}/generate | Invoke a registered Handbook agent non-streaming. |
POST | /handbook/agents/{agentSlug}/stream | Invoke a registered Handbook agent with SSE streaming. |
Discover exact slugs from /handbook/routes.json in the active environment rather than hard-coding slug assumptions.
Registered Handbook Tools
| Tool ID | Purpose |
|---|---|
handbook-search-policy-evidence | Search policy evidence through the Handbook product retrieval contract. |
handbook-generate-verified-answer | Generate a verified answer package grounded in retrieved Handbook policy evidence. |
Source: packages/domain-handbook/src/tools/index.ts.
Runtime-Registered Handbook Workflows
The runtime registers 17 Handbook workflows through loadHandbookArtifacts(). These are the workflows that should appear through /handbook/routes.json and generated /handbook/workflows/* routes when the Handbook domain is enabled.
| Runtime workflow key | Product workflow ID | Purpose |
| --- | --- |
| msba-generate-verified-answer | n/a | Generate a verified answer package grounded in retrieved evidence. |
| handbook-understand-source-document | handbook.understand-source-document.v1 | Parse and understand source PDFs/documents. |
| handbook-classify-document | handbook.classify-document.v1 | Classify coverage, audience, level, and scope. |
| handbook-extract-source-answers | handbook.extract-source-answers.v1 | Extract source answer rows and classification output. |
| handbook-extract-source-context | handbook.extract-source-context.v1 | Synthesize and persist provenance-backed source-context memory from uploaded handbook evidence. |
| handbook-generate-complete-handbook | handbook.generate-complete-handbook.v1 | Generate deterministic and policy-backed handbook sections. |
| handbook-review-candidate | handbook.review-candidate.v1 | Review generated candidate warnings and overrides. |
| handbook-revise-candidate-section | handbook.revise-candidate-section.v1 | Revise one candidate section with copy-on-write section artifacts. |
| handbook-render-document | handbook.render-document.v1 | Render document exports. |
| handbook-promote-candidate-handbook | handbook.promote-candidate-handbook.v1 | Promote a reviewed candidate handbook. |
| handbook-run-policy-adherence | handbook.run-policy-adherence.v1 | Evaluate policy adherence for a candidate/active handbook. |
| handbook-compare-handbooks | handbook.compare-handbooks.v1 | Compare handbooks for the same scope/type. |
| handbook-diff-corpus-versions | handbook.diff-corpus-versions.v1 | Diff corpus versions. |
| handbook-run-policy-review | handbook.run-policy-review.v1 | Run the policy-review pipeline over selected indexed artifacts. |
| handbook-product-flow-lab | handbook.product-flow-lab.v1 | Exercise the broad Admin product-flow harness. |
| handbook-prototype-candidate-chain | handbook.prototype-candidate-chain.v1 | Run the prototype-derived question/answer/candidate-release chain. |
| handbook-rag-validation | n/a | Validate RAG ingestion, processing evidence, and corpus query behavior. |
Source: packages/domain-handbook/src/loader.ts.
handbook-ingestion-profile and msba-pdf-to-verified-answer are exported from the package for scripts/tests/direct callers, but are not currently registered by loadHandbookArtifacts() as runtime routes.
Focused Handbook Application API
The focused app route adapter is apps/handbook-app/server/routes.ts. Its
active route families are:
| Route family | Purpose |
|---|---|
GET /api/health, GET /api/healthz, GET /api/runtime-config | Health and browser runtime configuration. |
/api/district-profiles/**, /api/district-source-context | District profile import/listing and persisted source-context discovery. |
/api/handbooks/** | Handbook library and start-review actions. |
/api/compliance/runs/**, /api/compliance/reviews/** | Ingestion/review runs, cancellation, proof, findings, reviewer context, remediation decisions/chat, and reviewer outcomes. |
/api/generations/** | Create, inspect, list, and download generated compliance artifacts. |
/api/dev/reviewable-source-artifacts/** | Development-only inspection of reviewable-source projections. |
Use apps/handbook-app/src/api-client-react/index.ts and its generated module
for the browser-facing DTOs.
The exact request/response semantics are route-specific and should be verified
against the server adapter before adding another client.
Admin BFF: RAG And PDF Preparation
These routes are implemented in apps/admin-api/src/routes/admin/handbook-rag.ts and documented in packages/admin-contracts/openapi.yaml.
| Method | BFF path after /admin-api | Purpose |
|---|---|---|
GET | /admin/handbook/rag-presets | Read Handbook RAG workflow state, candidate bundles, active corpus, and workbench metadata. |
GET | /admin/handbook/rag-presets/active-sources | Read active source/index information for the promoted Handbook corpus. |
POST | /admin/handbook/rag-presets/pdf-jobs | Create a PDF preparation job. Use preparationMode: "reviewable-unit-v2" or policyReviewPreparation: true to prepare an uploaded handbook for policy review. |
GET | /admin/handbook/rag-presets/pdf-jobs/:jobId | Read PDF preparation job state. |
POST | /admin/handbook/rag-presets/pdf-jobs/:jobId/work-item | Link a PDF job to a work item. |
POST | /admin/handbook/rag-presets/pdf-jobs/:jobId/complete | Complete a PDF preparation job. |
POST | /admin/handbook/rag-presets/pdf-jobs/:jobId/fail | Mark a PDF preparation job failed. |
POST | /admin/handbook/rag-presets/candidates | Create a candidate RAG preset/corpus bundle. |
POST | /admin/handbook/rag-presets/candidates/:bundleId/retire | Retire a candidate bundle. |
POST | /admin/handbook/rag-presets/candidates/:bundleId/cleanup | Clean up a candidate bundle/index. |
POST | /admin/handbook/rag-presets/promote | Promote a candidate Handbook corpus. |
POST | /admin/handbook/rag-presets/rollback | Roll back the latest promotion. |
POST | /admin/handbook/rag-presets/reset | Reset local Handbook RAG workflow state. |
POST | /admin/handbook/rag-presets/answers | Run a live answer probe against the active promoted corpus. |
GET | /admin/handbook/rag-presets/answers/:answerPackageId | Read saved answer audit detail. |
Admin BFF: Product Checks
| Method | BFF path after /admin-api | Purpose |
|---|---|---|
POST | /admin/handbook/product-checks/prototype-candidate-chain | Run the prototype candidate chain check from the Admin workbench. |
POST | /admin/handbook/product-checks/product-flow-lab | Run the product-flow lab harness. |
POST | /admin/handbook/product-workflows/:workflowSlug | Execute a registered Handbook product workflow action from the Admin workbench. |
Admin BFF: Policy Review
All policy-review mutations return the same dashboard projection, handbook.policy-review-admin-dashboard.v1, so the UI can refresh selectors, job state, saved runs, findings, checklist review, and diagnostics after each call.
| Method | BFF path after /admin-api | Request body | Purpose |
|---|---|---|---|
GET | /admin/handbook/policy-review | none | Read the dashboard projection, including DB-backed artifact options, selected policy/handbook artifacts, active job, job history, saved runs, run detail, checklist review, and diagnostics. |
POST | /admin/handbook/policy-review/run | { ownerScopeId?, policyArtifactId?, handbookArtifactId? } | Enqueue a policy-review run for the selected indexed policy and handbook artifacts. |
POST | /admin/handbook/policy-review/retry | { jobId? } | Retry a failed policy-review job. |
POST | /admin/handbook/policy-review/resume | { runId } | Load a saved run back into the dashboard projection. |
POST | /admin/handbook/policy-review/findings/:findingId/actions | { action, reviewerId?, note? } | Record a reviewer action: mark_reviewed, request_district_input, accept_suggested_wording, dismiss_as_local_only, or reopen. |
POST | /admin/handbook/policy-review/findings/:findingId/feedback | { evidenceQuality, reasoningQuality, outcomeAccuracy, reviewerId?, note? } | Record quality feedback for a finding. |
Data Contract Sources
- Admin BFF route source:
apps/admin-api/src/routes/admin/handbook-rag.ts - Browser API client and TypeScript DTOs:
apps/admin-ui/src/api-client/handbook-rag.ts - Admin BFF OpenAPI:
packages/admin-contracts/openapi.yaml - Ingestion and PDF job workflow state:
apps/admin-api/src/lib/handbook-rag-workflow.ts - Ingestion profiles:
packages/domain-handbook/src/ingestion-profiles/index.ts - Policy-review contracts:
packages/domain-handbook/src/policy-review-run/contracts.ts - Internal source-backed runbook:
docs/internal/handbook/policy-review-admin-api.md
For the shared Admin API framing, see Admin API.
For the end-to-end ingestion details behind the PDF job routes, see Ingestion And Indexing. For product route sequencing, see Handbook Workflows.