K12 API Reference

The K12 Safety API exposes 17 tools organized into three workflow families plus cancellation. Two endpoint styles are available -- choose whichever fits your integration.

Endpoint Style	Pattern	Request Body	Docs
Legacy	POST /ai/api/tools/{tool-id}/execute	{ "data": { ... } }	Legacy Endpoints
Domain Routes	POST /ai/k12/tools/{slug}	{ ... } (flat JSON)	Domain Routes

Both styles reach the same underlying tools, use the same authentication, and return the same data. Domain routes additionally expose workflow endpoints for sync/async execution.

---

Authentication

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

Obtaining a Token

TOKEN=$(curl -s -X POST \
  "https://login.microsoftonline.com/ef3e1dbf-4cc9-4a06-bc23-71dd7a46fd1b/oauth2/v2.0/token" \
  -d "client_id={CLIENT_ID}" \
  -d "client_secret={CLIENT_SECRET}" \
  -d "scope=api://dev-k12-aitools-t27p-api/.default" \
  -d "grant_type=client_credentials" \
  | jq -r '.access_token')

Tokens expire after approximately 1 hour. Cache and refresh proactively.

note

Replace {CLIENT_ID} and {CLIENT_SECRET} with your credentials. These will be provided separately by your administrator.

Environments

Environment	Base URL	OAuth Scope
Development	https://dev-k12-aitools-t27p-apim.azure-api.net	api://dev-k12-aitools-t27p-api/.default

note

The subscription key and client credentials will be provided separately by your administrator.

---

Tool Inventory

Tool ID	Domain Slug	Group	Purpose
k12-district-planning-kickoff	district-planning-kickoff	EOP Editing	Start district-level EOP planning edits
k12-facility-planning-kickoff	facility-planning-kickoff	EOP Editing	Start facility-level EOP planning edits
k12-functional-annex-kickoff	functional-annex-kickoff	EOP Editing	Start functional annex editing
k12-hazard-annex-kickoff	hazard-annex-kickoff	EOP Editing	Start hazard annex editing
k12-functional-annex-suggest-roles-kickoff	functional-annex-suggest-roles-kickoff	EOP Editing	Suggest missing roles for a functional annex
k12-hazard-annex-suggest-roles-kickoff	hazard-annex-suggest-roles-kickoff	EOP Editing	Suggest missing roles for a hazard annex
k12-annex-editing-kickoff	annex-editing-kickoff	EOP Editing	Compatibility kickoff for general EOP annex editing
k12-annex-editing-status	annex-editing-status	EOP Editing	Poll editing status
k12-annex-editing-result	annex-editing-result	EOP Editing	Fetch editing result
k12-qrg-generation-kickoff	qrg-generation-kickoff	QRG Generation	Start QRG generation from EOP
k12-qrg-generation-status	qrg-generation-status	QRG Generation	Poll generation status
k12-qrg-generation-result	qrg-generation-result	QRG Generation	Fetch generated QRGs
k12-qrg-editing-kickoff	qrg-editing-kickoff	QRG Editing	Start QRG section editing
k12-qrg-editing-status	qrg-editing-status	QRG Editing	Poll editing status
k12-qrg-editing-result	qrg-editing-result	QRG Editing	Fetch editing result
k12-cancel-task-request	cancel-task-request	Cancellation	Cancel EOP editing job
k12-qrg-cancel	qrg-cancel	Cancellation	Cancel QRG generation or editing job

---

Async Integration Pattern

All tool groups follow the same three-step pattern: kickoff, poll, fetch.

Status Values

Status	Terminal	Used By
accepted	No	All workflows
processing / PROCESSING	No	EOP/QRG Editing (lowercase), QRG Generation (uppercase)
success / SUCCESS	Yes	EOP/QRG Editing (lowercase), QRG Generation (uppercase)
error / ERROR	Yes	EOP/QRG Editing (lowercase), QRG Generation (uppercase)
cancelled / CANCELLED	Yes	EOP/QRG Editing (lowercase), QRG Generation (uppercase)

warning

EOP Editing and QRG Editing use lowercase statuses. QRG Generation uses UPPERCASE. Your polling logic must handle both conventions.

---

Error Responses

HTTP Status	Meaning
400	Missing required fields or invalid format (legacy endpoints)
401	Invalid or expired token, or missing subscription key
403	Token lacks the required scope for this environment
404	Tool ID or resource not found
422	Validation error (domain routes; also legacy for some tool-level errors)
429	Rate limit exceeded
500	Internal server error

---

Next Steps

Legacy Endpoints

Complete schemas, field tables, and curl examples using /api/tools/.../execute

Domain Routes

Flat JSON endpoints, workflow routes, and curl examples using /k12/tools/...