Domain Routes

Domain-scoped routes offer cleaner URLs, flat JSON request bodies (no data wrapper), and direct access to workflow operations as an alternative to the legacy endpoints.

Both endpoint styles reach the same underlying tools and return the same data. Choose whichever fits your integration best.

note

Platform observability improvements do not require integration changes. Keep using the same request body and response handling documented here. For async kickoff calls, an initial accepted response means the job was queued; use the matching status and result endpoints to determine whether the background job completed or failed.

Key Differences from Legacy Endpoints

	Legacy (`/ai/api/tools/.../execute`)	Domain (`/ai/k12/tools/...`)
Base pattern	`POST /ai/api/tools/{tool-id}/execute`	`POST /ai/k12/tools/{slug}`
Request body	`{ "data": { ... } }`	`{ ... }` (flat JSON, no wrapper)
Validation errors	400 Bad Request	422 Unprocessable Entity
Workflow access	Not available	Full workflow routes (sync, async, polling)
Tool slug	Full ID (e.g., `k12-qrg-generation-kickoff`)	Domain prefix stripped (e.g., `qrg-generation-kickoff`)

Authentication is identical -- the same Authorization, Ocp-Apim-Subscription-Key, and Content-Type headers are required. See API Reference Overview for details.

Tool Routes

Pattern

POST {BASE_URL}/ai/k12/tools/{slug}

Tool Slug Mapping

The k12- prefix is stripped from the tool ID to form the slug:

Tool ID	Domain Route Slug	Domain Route Path
`k12-district-planning-kickoff`	`district-planning-kickoff`	`/ai/k12/tools/district-planning-kickoff`
`k12-facility-planning-kickoff`	`facility-planning-kickoff`	`/ai/k12/tools/facility-planning-kickoff`
`k12-functional-annex-kickoff`	`functional-annex-kickoff`	`/ai/k12/tools/functional-annex-kickoff`
`k12-hazard-annex-kickoff`	`hazard-annex-kickoff`	`/ai/k12/tools/hazard-annex-kickoff`
`k12-functional-annex-suggest-roles-kickoff`	`functional-annex-suggest-roles-kickoff`	`/ai/k12/tools/functional-annex-suggest-roles-kickoff`
`k12-hazard-annex-suggest-roles-kickoff`	`hazard-annex-suggest-roles-kickoff`	`/ai/k12/tools/hazard-annex-suggest-roles-kickoff`
`k12-annex-editing-kickoff`	`annex-editing-kickoff`	`/ai/k12/tools/annex-editing-kickoff`
`k12-annex-editing-status`	`annex-editing-status`	`/ai/k12/tools/annex-editing-status`
`k12-annex-editing-result`	`annex-editing-result`	`/ai/k12/tools/annex-editing-result`
`k12-qrg-generation-kickoff`	`qrg-generation-kickoff`	`/ai/k12/tools/qrg-generation-kickoff`
`k12-qrg-generation-status`	`qrg-generation-status`	`/ai/k12/tools/qrg-generation-status`
`k12-qrg-generation-result`	`qrg-generation-result`	`/ai/k12/tools/qrg-generation-result`
`k12-qrg-editing-kickoff`	`qrg-editing-kickoff`	`/ai/k12/tools/qrg-editing-kickoff`
`k12-qrg-editing-status`	`qrg-editing-status`	`/ai/k12/tools/qrg-editing-status`
`k12-qrg-editing-result`	`qrg-editing-result`	`/ai/k12/tools/qrg-editing-result`
`k12-cancel-task-request`	`cancel-task-request`	`/ai/k12/tools/cancel-task-request`
`k12-qrg-cancel`	`qrg-cancel`	`/ai/k12/tools/qrg-cancel`

Request Format

Domain routes accept a flat JSON body -- the same fields documented in the Legacy Endpoints, but without the data wrapper.

Legacy:

{
  "data": {
    "emergencyOperationPlanId": "d4e5f6a7-...",
    "waitForResult": false
  }
}

Domain route:

{
  "emergencyOperationPlanId": "d4e5f6a7-...",
  "waitForResult": false
}

Response Format

Successful tool responses are wrapped in a data envelope (same as legacy):

{
  "data": {
    "requestId": "a1b2c3d4-...",
    "sessionId": "b2c3d4e5-...",
    "status": "accepted"
  }
}

For async kickoff tools, the accepted response confirms the server created the job and started background processing. It does not guarantee the background generation has finished. Poll the matching status endpoint, then call the matching result endpoint when the status indicates completion.

Validation errors return 422 with an error field:

{
  "error": "Validation failed: emergencyOperationPlanId is required"
}

Tool Examples

Functional Annex Kickoff

curl -X POST "${BASE_URL}/ai/k12/tools/functional-annex-kickoff" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Ocp-Apim-Subscription-Key: $SUBSCRIPTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emergencyOperationPlanId": "d4e5f6a7-b8c9-0123-d456-e78901234567",
    "userId": "user-456",
    "roleId": "safety-coordinator",
    "form": {
      "name": "Fire Safety Annex",
      "field": {
        "group": "Response Procedures",
        "name": "evacuation_steps",
        "content": "<p>Current evacuation procedures.</p>"
      }
    },
    "prompt": "Add assembly point verification step"
  }'

EOP Editing Status

curl -X POST "${BASE_URL}/ai/k12/tools/annex-editing-status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Ocp-Apim-Subscription-Key: $SUBSCRIPTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{"requestIds": ["req-7f3a..."]}'

EOP Editing Result

curl -X POST "${BASE_URL}/ai/k12/tools/annex-editing-result" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Ocp-Apim-Subscription-Key: $SUBSCRIPTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{"requestId": "req-7f3a..."}'

QRG Generation Kickoff

curl -X POST "${BASE_URL}/ai/k12/tools/qrg-generation-kickoff" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Ocp-Apim-Subscription-Key: $SUBSCRIPTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emergencyOperationPlanId": "d4e5f6a7-b8c9-0123-d456-e78901234567",
    "generalUserTagIds": ["a1b2c3d4-e5f6-7890-abcd-100000000001"],
    "sessionId": null,
    "waitForResult": false
  }'

QRG Generation Status

curl -X POST "${BASE_URL}/ai/k12/tools/qrg-generation-status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Ocp-Apim-Subscription-Key: $SUBSCRIPTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{"requestIds": ["a1b2c3d4-..."]}'

QRG Generation Result

curl -X POST "${BASE_URL}/ai/k12/tools/qrg-generation-result" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Ocp-Apim-Subscription-Key: $SUBSCRIPTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{"requestId": "a1b2c3d4-..."}'

QRG Editing Kickoff

curl -X POST "${BASE_URL}/ai/k12/tools/qrg-editing-kickoff" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Ocp-Apim-Subscription-Key: $SUBSCRIPTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-456",
    "roleId": "a1b2c3d4-e5f6-7890-abcd-100000000001",
    "section": "DURING",
    "content": "<ul><li>Alert students calmly and begin evacuation</li></ul>",
    "prompt": "Add a step about checking classroom headcount before leaving",
    "sessionId": null,
    "quickReferenceGuide": {
      "name": "Fire Safety - Teacher",
      "type": "EMERGENCY",
      "instructionFor": "FIRE",
      "generalUserTagManagementType": "ASSIGN_SELECTED",
      "generalUserTags": [
        { "label": "Teacher", "value": "a1b2c3d4-e5f6-7890-abcd-100000000001" }
      ],
      "organization": {
        "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
        "name": "Lincoln Elementary",
        "type": "FACILITY"
      }
    }
  }'

QRG Editing Status

curl -X POST "${BASE_URL}/ai/k12/tools/qrg-editing-status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Ocp-Apim-Subscription-Key: $SUBSCRIPTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{"requestIds": ["req-abc..."]}'

QRG Editing Result

curl -X POST "${BASE_URL}/ai/k12/tools/qrg-editing-result" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Ocp-Apim-Subscription-Key: $SUBSCRIPTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{"requestId": "req-abc..."}'

Cancel EOP Editing

curl -X POST "${BASE_URL}/ai/k12/tools/cancel-task-request" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Ocp-Apim-Subscription-Key: $SUBSCRIPTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{"requestId": "req-7f3a..."}'

Cancel QRG Job

curl -X POST "${BASE_URL}/ai/k12/tools/qrg-cancel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Ocp-Apim-Subscription-Key: $SUBSCRIPTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{"requestId": "a1b2c3d4-...", "jobType": "generation"}'

Workflow Routes

Domain routes also expose direct workflow access, which is not available through the legacy tool endpoints. Workflows provide synchronous execution, async execution with run tracking, and status polling.

Available Workflows

Workflow	Domain Route	Purpose
EOP Annex Editing	`/ai/k12/workflows/annex`	Edit EOP annex content
QRG Generation	`/ai/k12/workflows/qrg-generation`	Generate QRGs from an EOP
QRG Editing	`/ai/k12/workflows/qrg-editing`	Edit a QRG section

Synchronous Execution

Blocks until the workflow completes and returns the result.

POST {BASE_URL}/ai/k12/workflows/{slug}

curl -X POST "${BASE_URL}/ai/k12/workflows/qrg-generation" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Ocp-Apim-Subscription-Key: $SUBSCRIPTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emergencyOperationPlanId": "d4e5f6a7-b8c9-0123-d456-e78901234567"
  }'

Response:

{
  "status": "success",
  "result": {
    "requestId": "a1b2c3d4-...",
    "sessionId": "b2c3d4e5-...",
    "status": "success",
    "qrgList": { "root": [ ... ] },
    "aiStats": { ... }
  }
}

warning

Synchronous execution blocks the HTTP connection until the workflow finishes. For QRG generation with large EOPs, this can take several minutes. Use async execution for production integrations.

Async Execution

Starts the workflow in the background and returns a runId for polling.

POST {BASE_URL}/ai/k12/workflows/{slug}/start-async

curl -X POST "${BASE_URL}/ai/k12/workflows/qrg-generation/start-async" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Ocp-Apim-Subscription-Key: $SUBSCRIPTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emergencyOperationPlanId": "d4e5f6a7-b8c9-0123-d456-e78901234567"
  }'

Response:

{
  "runId": "run-9e8d7c6b-5a4f-3210-fedc-ba9876543210",
  "message": "Workflow started in background. Poll for status."
}

Poll Run Status

Check the status and result of an async workflow run.

GET {BASE_URL}/ai/k12/workflows/{slug}/runs/{runId}

curl "${BASE_URL}/ai/k12/workflows/qrg-generation/runs/run-9e8d7c6b-..." \
  -H "Authorization: Bearer $TOKEN" \
  -H "Ocp-Apim-Subscription-Key: $SUBSCRIPTION_KEY"

Field Reference

For complete request and response field documentation (types, constraints, nested objects), see the Legacy Endpoints. The fields are identical -- the only difference is that domain routes accept them as a flat JSON body instead of inside a data wrapper.

Next Steps

Legacy Endpoints

Complete field-level schemas for all 17 tools with curl examples

Implementation Guide

End-to-end integration walkthrough with both endpoint styles

Key Differences from Legacy Endpoints​

Tool Routes​

Pattern​

Tool Slug Mapping​

Request Format​

Response Format​

Tool Examples​

Functional Annex Kickoff​

EOP Editing Status​

EOP Editing Result​

QRG Generation Kickoff​

QRG Generation Status​

QRG Generation Result​

QRG Editing Kickoff​

QRG Editing Status​

QRG Editing Result​

Cancel EOP Editing​

Cancel QRG Job​

Workflow Routes​

Available Workflows​

Synchronous Execution​

Async Execution​

Poll Run Status​

Field Reference​

Next Steps​