Skip to main content

K12 Tools & Endpoints

Authentication​

When calling K12 tools through the K12 Azure Dev APIM, both authentication methods are required:

  1. OAuth JWT Token (Bearer) - Required for user authorization and tenant verification
  2. APIM Subscription Key - Required for API gateway access control

Both headers must be present in all requests. See docs/reference/workflows/k12/*-tool-endpoints.md for the exact header list and examples.

Tool Endpoints​

Legacy Tool Execute (Current)​

All tools are available via the legacy endpoint: POST /ai/api/tools/{toolId}/execute with a { "data": { ... } } wrapper. This is the endpoint APIM proxies for external consumers.

Domain Routes (Alternative)​

Domain-scoped routes are also available with descriptive paths and flat JSON bodies (no data wrapper):

POST /ai/k12/tools/{slug}                    -- Direct tool execution
POST /ai/k12/workflows/{slug}                -- Synchronous workflow
POST /ai/k12/workflows/{slug}/start-async    -- Async workflow (returns runId)
GET  /ai/k12/workflows/{slug}/runs/{runId}   -- Poll workflow status

Key differences: domain routes return 422 for validation errors (not 400), accept flat JSON input, and use descriptive URLs for cleaner network monitoring (e.g., /ai/k12/tools/qrg-generation-kickoff instead of /ai/api/tools/k12-qrg-generation-kickoff/execute).

See packages/platform-runtime/src/server/routes/domain-tool.routes.ts and packages/platform-runtime/src/server/routes/domain-workflow.routes.ts for implementation details.

Tool IDs​

Common tool IDs:

  • k12-annex-editing-kickoff
  • k12-district-planning-kickoff
  • k12-facility-planning-kickoff
  • k12-functional-annex-kickoff
  • k12-hazard-annex-kickoff
  • k12-functional-annex-suggest-roles-kickoff
  • k12-hazard-annex-suggest-roles-kickoff
  • k12-annex-editing-status
  • k12-annex-editing-result
  • k12-get-selected-eop-roles
  • k12-get-eop-role-universe
  • k12-get-emergency-operation-plan-snapshot
  • k12-qrg-editing-kickoff
  • k12-qrg-editing-status
  • k12-qrg-editing-result
  • k12-qrg-generation-kickoff
  • k12-qrg-generation-status
  • k12-qrg-generation-result
  • k12-qrg-cancel
  • k12-cancel-task-request

Additional implemented K12 MCP tools (internal logging / persistence utilities):

  • k12-insert-task-request-log
  • k12-insert-task-in-monitoring-table
  • k12-update-task-status
  • k12-update-task-request-response
  • k12-lkp-task-status-by-session-or-request
  • k12-lkp-task-request-result

Tool Quick Reference​

  • EOP tools

    • k12-district-planning-kickoff — Kick off district-level EOP planning edits. Details → (./tools-detailed#k12-annex-editing-kickoff)
    • k12-facility-planning-kickoff — Kick off facility-level EOP planning edits. Details → (./tools-detailed#k12-annex-editing-kickoff)
    • k12-functional-annex-kickoff — Kick off functional annex editing. Details → (./tools-detailed#k12-annex-editing-kickoff)
    • k12-hazard-annex-kickoff — Kick off hazard annex editing. Details → (./tools-detailed#k12-annex-editing-kickoff)
    • k12-functional-annex-suggest-roles-kickoff — Suggest missing roles for a functional annex. Details → (./tools-detailed#k12-annex-editing-kickoff)
    • k12-hazard-annex-suggest-roles-kickoff — Suggest missing roles for a hazard annex. Details → (./tools-detailed#k12-annex-editing-kickoff)
    • k12-annex-editing-kickoff — Compatibility kickoff for general EOP annex editing. Details → (./tools-detailed#k12-annex-editing-kickoff)
    • k12-annex-editing-status — Poll EOP editing status. Details → (./tools-detailed#k12-annex-editing-kickoff)
    • k12-annex-editing-result — Fetch final EOP edit results. Details → (./tools-detailed#k12-annex-editing-kickoff)
    • k12-get-selected-eop-roles — Resolve the selected EOP role set used by annex workflows. Details → (./tools-detailed#k12-annex-editing-kickoff)
    • k12-get-eop-role-universe — Resolve the organization role universe used by suggest-role flows. Details → (./tools-detailed#k12-annex-editing-kickoff)
    • k12-get-emergency-operation-plan-snapshot — Fetch a canonical EOP snapshot for context. Details → (./tools-detailed#k12-get-emergency-operation-plan-snapshot)
    • k12-cancel-task-request — Cancel an EOP workflow request/job. Details → (./tools-detailed#k12-cancel-task-request)
    • k12-insert-task-request-log — Persist raw request payload for audit. Details → (./tools-detailed#k12-insert-task-request-log)
    • k12-insert-task-in-monitoring-table — Insert monitoring/status row. Details → (./tools-detailed#k12-insert-task-in-monitoring-table)
    • k12-update-task-status — Update monitoring status. Details → (./tools-detailed#k12-update-task-status)
    • k12-update-task-request-response — Persist final response payload. Details → (./tools-detailed#k12-update-task-request-response)
    • k12-lkp-task-status-by-session-or-request — Read status history. Details → (./tools-detailed#k12-lkp-task-status-by-session-or-request)
    • k12-lkp-task-request-result — Read saved request+result. Details → (./tools-detailed#k12-lkp-task-request-result)

  • QRG tools

    • k12-qrg-generation-kickoff — Kick off QRG generation. Details → (./tools-detailed#k12-qrg-generation-kickoff)
    • k12-qrg-generation-status — Poll QRG generation status. Details → (./tools-detailed#k12-qrg-generation-status)
    • k12-qrg-generation-result — Fetch generated QRG results. Details → (./tools-detailed#k12-qrg-generation-result)
    • k12-qrg-editing-kickoff — Kick off QRG editing job. Details → (./tools-detailed#k12-qrg-editing-kickoff)
    • k12-qrg-editing-status — Poll QRG editing status. Details → (./tools-detailed#k12-qrg-editing-status)
    • k12-qrg-editing-result — Fetch edited QRG results. Details → (./tools-detailed#k12-qrg-editing-result)
    • k12-qrg-cancel — Cancel QRG generation/editing. Details → (./tools-detailed#k12-qrg-cancel)

Programmatic usage (Node)​

You can call the kickoff logic directly from code for test harnesses or scripts:

import { runAnnexWorkflowKickoff } from 'packages/domain-k12/src/annex-editing-workflow-runner.ts';

const result = await runAnnexWorkflowKickoff({ input: { emergencyOperationPlan: { id: 'plan-1', organizationId: 'org-1' }, userId: 'u1', roleId: 'r1', form: { field: { content: '<p>...</p>' } } } });

HTTP usage (APIM / Mastra HTTP API)​

  • POST to /ai/api/tools/k12-annex-editing-kickoff/execute with { "data": { ... } } and expect { requestId, sessionId, status } in the accepted case.
  • For new integrations, prefer the four primary EOP kickoff tools and reserve k12-annex-editing-kickoff for compatibility.
  • k12-functional-annex-kickoff and k12-hazard-annex-kickoff automatically switch to suggest-role mode when the prompt normalizes to Suggest Roles and Responsibilities.

See docs/reference/workflows/k12/*-tool-endpoints.md for full request/response examples and sample cURL commands.

Example: Kickoff (EOP — tool IDs keep 'annex' naming)​

curl -X POST "$BASE_URL/ai/api/tools/k12-annex-editing-kickoff/execute" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Ocp-Apim-Subscription-Key: $SUBSCRIPTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data": {"emergencyOperationPlan": {"id": "plan-sample", "organizationId": "org-sample"}, "userId": "principal@example.edu", "roleId": "safety-coordinator", "form": {"field": {"content": "<p>...</p>"}}}}'

Operational notes​

  • requestId and sessionId are returned by kickoff; use them to poll status and fetch results.
  • The cancel tool updates DB rows and acts as the canonical way to request job cancellation.
  • Tools perform validation using shared Zod schemas under packages/domain-k12/src/ and propagate structured errors.