K12 Tools Endpoint Reference

This page documents the authentication requirements, common endpoint pattern, and full tool inventory for the K12 Safety API. All 11 external-facing tools share the same execution model and authentication flow described here.

---

Authentication and Environments

note

For full setup instructions including prerequisites, token acquisition, environment base URLs, and required headers, see the Authentication and Setup page.

Every API call requires three headers:

Header	Value
Authorization	Bearer {access_token} (OAuth 2.0 client credentials)
Ocp-Apim-Subscription-Key	{subscription_key}
Content-Type	application/json

Legacy Tool Execute (Current)

All K12 tools share a single execution endpoint:

POST {BASE_URL}/ai/api/tools/{tool-id}/execute

Every request body wraps tool-specific inputs inside a data envelope:

{
  "data": {
    "field1": "value1",
    "field2": "value2"
  }
}

The response structure varies by tool but always returns JSON. Kickoff tools return tracking identifiers; status tools return progress information; result tools return the completed output.

Domain Routes (Alternative)

The API also exposes domain-scoped routes with descriptive URLs and flat request bodies:

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

Domain routes accept a flat JSON body (no data wrapper) and return 422 for validation errors instead of 400. Both endpoint styles reach the same underlying tools.

Example: To call k12-qrg-generation-kickoff via the domain route:

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",
    "waitForResult": false
  }'

Domain workflow routes are also available:

POST {BASE_URL}/ai/k12/workflows/{slug}                -- Synchronous execution
POST {BASE_URL}/ai/k12/workflows/{slug}/start-async    -- Async (returns runId)
GET  {BASE_URL}/ai/k12/workflows/{slug}/runs/{runId}   -- Poll run status

note

The examples in this documentation use the legacy /ai/api/tools/.../execute endpoint. Domain routes can be used interchangeably by dropping the data wrapper from the request body and using the domain path instead.

---

Tool Quick Reference

The K12 Safety API exposes 19 tools organized into three groups plus cancellation tools:

EOP Editing

Tool ID	Description	Details
k12-district-planning-kickoff	Start district-level EOP planning edits	Uses the EOP kickoff schema
k12-facility-planning-kickoff	Start facility-level EOP planning edits	Uses the EOP kickoff schema
k12-functional-annex-kickoff	Start functional annex editing	Uses the EOP kickoff schema
k12-hazard-annex-kickoff	Start hazard annex editing	Uses the EOP kickoff schema
k12-functional-annex-suggest-roles-kickoff	Suggest missing roles for a functional annex	Uses the EOP kickoff schema
k12-hazard-annex-suggest-roles-kickoff	Suggest missing roles for a hazard annex	Uses the EOP kickoff schema
k12-annex-editing-kickoff	Compatibility kickoff for general EOP annex editing	View schema
k12-annex-editing-status	Check status of an editing job	View schema
k12-annex-editing-result	Fetch the result of a completed editing job	View schema

EOP Role Context

Tool ID	Description	Details
k12-get-selected-eop-roles	Resolve the currently selected EOP roles	Returns the EOP-scoped role set used by annex workflows
k12-get-eop-role-universe	Resolve the organization role universe for the EOP	Returns selected roles plus the organization role universe used for suggest-role flows

QRG Generation

Tool ID	Description	Details
k12-qrg-generation-kickoff	Start QRG generation from an EOP	View schema
k12-qrg-generation-status	Check status of a QRG generation job	View schema
k12-qrg-generation-result	Fetch generated QRGs from a completed job	View schema

QRG Editing

Tool ID	Description	Details
k12-qrg-editing-kickoff	Start a QRG section editing job	View schema
k12-qrg-editing-status	Check status of a QRG editing job	View schema
k12-qrg-editing-result	Fetch the result of a completed QRG edit	View schema

Cancellation

Tool ID	Description	Details
k12-cancel-task-request	Cancel a pending or in-progress EOP editing job	View schema
k12-qrg-cancel	Cancel a pending QRG generation or editing job	View schema

---

Async Integration Pattern

All tool groups that perform AI processing follow the same three-step asynchronous pattern: kickoff, poll, fetch result.

Step 1: Kickoff

Call the kickoff tool with the required inputs. The response returns immediately with a requestId and sessionId that you must persist for subsequent calls.

Kickoff response fields:

Field	Type	Description
requestId	string	Unique identifier for this job; use it to poll status and fetch results
sessionId	string	Session identifier for correlating related operations
status	string	Always accepted on successful kickoff
message	string	Human-readable confirmation

Step 2: Poll Status

Pass the requestId (in an array) to the corresponding status tool. Repeat until the status reaches a terminal value.

Possible status values:

Status	Terminal	Meaning
accepted	No	Job received and queued
processing	No	Job is actively running
success / SUCCESS	Yes	Job completed successfully
error / ERROR	Yes	Job failed
cancelled / CANCELLED	Yes	Job was cancelled

warning

EOP editing tools return lowercase statuses (success, error). QRG generation tools return uppercase statuses (SUCCESS, ERROR). Your polling logic must handle both conventions.

Step 3: Fetch Result

Once a terminal status is reached, call the result tool with the requestId to retrieve the full output.

Cancellation

To cancel a running or queued QRG job, call k12-qrg-cancel with the requestId and the jobType (generation or editing). To cancel an EOP editing job, call k12-cancel-task-request with the requestId.

---

Example: Full Kickoff Request

The following curl command kicks off an EOP annex editing job in the Development environment. Provide exactly one identity source: emergencyOperationPlanId or emergencyOperationPlan for persisted plans, emergencyOperationPlanConfigurationId or emergencyOperationPlanConfiguration for pre-EOP configuration-stage plans, or eopMasterCopyId/emergencyOperationPlanMasterCopy for Master Copy editing. The selected request object should send organizationId; the workflow uses that organization ID directly for district/organization details and does not derive it through EOP, configuration, or Master Copy lookups. Frontend-provided roles, userTags, or generalUserTags override backend-resolved role tags for prompt context; userTagIds may be an empty array while tag filling is pending.

curl -X POST "https://dev-k12-aitools-t27p-apim.azure-api.net/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-abc123",
        "organizationId": "org-789",
        "organization": {
          "id": "org-789",
          "name": "District One"
        }
      },
      "userId": "user-456",
      "userTagIds": [],
      "roles": [
        { "id": "tag-principal", "name": "Principal" }
      ],
      "form": {
        "name": "Fire Safety Annex",
        "field": {
          "group": "Response Procedures",
          "name": "evacuation_steps",
          "content": "<p>Current evacuation procedures for the main building.</p>"
        }
      },
      "prompt": "Add assembly point verification step after building clearance"
    }
  }'

Expected response:

{
  "requestId": "req-7f3a2b1c-d4e5-6789-abcd-ef0123456789",
  "sessionId": "sess-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "accepted",
  "message": "Editing job accepted and queued for processing"
}

---

Error Responses

When the API rejects a request, it returns a structured error:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Exactly one of emergencyOperationPlanId/emergencyOperationPlan, emergencyOperationPlanConfigurationId/emergencyOperationPlanConfiguration, or eopMasterCopyId/emergencyOperationPlanMasterCopy must be provided. Request objects may identify their source with id or organizationId; district/organization details require organizationId on the selected request object."
  }
}

HTTP Error Codes

Code	Meaning	When
400	Bad Request	Missing required fields, invalid field types, malformed JSON
401	Unauthorized	Invalid or expired bearer token, missing subscription key
403	Forbidden	Token lacks the required OAuth scope
404	Not Found	Unknown tool ID, or result not yet available for the given requestId
422	Validation Error	Domain route schema validation failed (field constraints violated)
429	Rate Limited	Too many requests -- back off and retry
500	Server Error	Internal failure during processing

Job-Level Failure States

When the HTTP request succeeds (200) but the async job itself fails, the status endpoint returns one of these terminal states:

Status	Meaning
ERROR	The job failed during processing (check the error message in the result)
CANCELLED	The job was cancelled via the cancel endpoint before completion
TIMEOUT	The job exceeded the maximum processing time

Non-terminal states: accepted (queued), PROCESSING (running).

EOP editing uses lowercase statuses. QRG generation and editing use UPPERCASE for terminal and processing states (the kickoff response uses lowercase accepted).

Common Error Scenarios

Scenario	Typical Error
Missing required field	400 with validation error naming the field
Invalid authentication token	401 Unauthorized
Missing subscription key	401 Unauthorized
Tool ID not found	404 Not Found
Rate limit exceeded	429 Too Many Requests
None or more than one of emergencyOperationPlanId/emergencyOperationPlan, emergencyOperationPlanConfigurationId/emergencyOperationPlanConfiguration, and eopMasterCopyId/emergencyOperationPlanMasterCopy provided	400 with specific validation message

---

Best Practices

• Persist identifiers -- Store the requestId and sessionId returned by kickoff calls. These are required for all subsequent operations.
• Poll with backoff -- Use exponential backoff when polling status endpoints. Start at 2 seconds and increase the interval.
• Handle both status conventions -- EOP editing uses lowercase statuses; QRG generation uses uppercase. Normalize before comparison.
• Expect partial success -- QRG generation processes each annex independently. The result may contain both successful QRGs and error entries for individual annexes.
• Use sessions for correlation -- When performing multiple edits in sequence, pass the sessionId from the first kickoff to subsequent calls for conversation continuity.

---

Next Steps

Detailed Tool Schemas

Complete request and response schemas for all 17 tools with curl examples

Domain Routes API

Alternative endpoints with flat JSON bodies and workflow routes

QRG Generation Deep Dive

In-depth reference for the QRG generation pipeline, AI stages, and output structure