Legacy Endpoints

Complete request/response schemas, field-level documentation, error responses, and curl examples for every K12 Safety tool using the legacy endpoint pattern.

Every request is a POST to:

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

All request bodies are wrapped in a data envelope. All examples use the Development base URL. For authentication and environment details, see the API Reference Overview.

note

These schemas also apply to the Domain Routes (/ai/k12/tools/{slug}), which accept the same fields as a flat JSON body without the data wrapper.

note

For async kickoff calls, an accepted response means the job was queued. Continue using the matching status and result endpoints to confirm completion or failure. Platform observability improvements do not change the documented request bodies or successful response bodies.

EOP Editing Tools

k12-annex-editing-kickoff

Compatibility endpoint for general EOP annex editing. New integrations should use the four primary kickoff tools that match the task: k12-district-planning-kickoff, k12-facility-planning-kickoff, k12-functional-annex-kickoff, or k12-hazard-annex-kickoff. The explicit k12-functional-annex-suggest-roles-kickoff and k12-hazard-annex-suggest-roles-kickoff endpoints remain available for compatibility and direct suggest-role invocations.

All EOP kickoff tools use the same request and response schema. The tool ID selects the agent profile and execution mode.

Property	Value
Endpoint	`POST /ai/api/tools/k12-annex-editing-kickoff/execute`
Scenario-specific endpoints	`POST /ai/api/tools/k12-district-planning-kickoff/execute`, `POST /ai/api/tools/k12-facility-planning-kickoff/execute`, `POST /ai/api/tools/k12-functional-annex-kickoff/execute`, `POST /ai/api/tools/k12-hazard-annex-kickoff/execute`, `POST /ai/api/tools/k12-functional-annex-suggest-roles-kickoff/execute`, `POST /ai/api/tools/k12-hazard-annex-suggest-roles-kickoff/execute`
Content-Type	`application/json`

For k12-functional-annex-kickoff and k12-hazard-annex-kickoff, prompts that normalize to Suggest Roles and Responsibilities automatically switch to the suggest-role execution mode.

Request

{
  "data": {
    "emergencyOperationPlan": {"id": "plan-abc123", "organizationId": "org-789"},
    "userId": "user-456",
    "roleId": "safety-coordinator",
    "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",
    "sessionId": null,
    "waitForResult": false
  }
}

Request Fields

Field	Type	Required	Description	Constraints
`emergencyOperationPlanId`	string	Conditional	EOP plan ID or snapshot ID to edit against. Organization context still requires `emergencyOperationPlan.organizationId`.	--
`emergencyOperationPlan`	object	Conditional	Frontend-provided EOP object. Its `id`, `emergencyOperationPlanId`, `planId`, or `eopId` is normalized as the plan identifier; `organizationId` is used directly for district/organization details.	Mutually exclusive with configuration and Master Copy identifiers
`emergencyOperationPlanConfigurationId`	string	Conditional	EOP configuration ID for source identity. Organization context still requires `emergencyOperationPlanConfiguration.organizationId`.	Mutually exclusive with plan and Master Copy identifiers
`emergencyOperationPlanConfiguration`	object	Conditional	Frontend-provided configuration object. Its ID aliases are normalized as the configuration identifier; `organizationId` is used directly for district/organization details.	Mutually exclusive with plan and Master Copy identifiers
`eopMasterCopyId`	string	Conditional	EOP Master Copy ID for pre-EOP template form editing. Organization context still requires `emergencyOperationPlanMasterCopy.organizationId`; supported by the legacy and scenario-specific EOP kickoff tools for district plan, facility plan, functional annex, and hazard annex Master Copies.	Mutually exclusive with plan and configuration identifiers
`emergencyOperationPlanMasterCopy`	object	Conditional	Frontend-provided Master Copy object. Saved objects may provide `id`, `eopMasterCopyId`, or another Master Copy ID alias. `organizationId` is used directly for district/organization details.	Mutually exclusive with plan and configuration identifiers
`userId`	string	Yes	Identifier of the user initiating the edit	Minimum 1 character
`roleId`	string	No	Optional role identifier retained for traceability	--
`userTagIds`	string[]	No	Alias for selected role/tag IDs. May be an empty array while frontend tag filling is pending.	--
`roles`, `userTags`, `generalUserTags`	array	No	Frontend-provided role/tag objects or names. These override backend-resolved role tags for prompt context when present.	--
`form`	object	Yes	Form data containing the content to edit	See nested fields below
`form.name`	string	No	Display name of the form being edited	--
`form.field`	object	Yes	The specific field within the form to edit	See nested fields below
`form.field.group`	string	No	Label for the field's group within the form	--
`form.field.name`	string	No	Name of the field being edited	--
`form.field.content`	string	No	Current HTML content of the field; empty string forces prompt-only mode	--
`prompt`	string	No	Natural language instruction describing the desired edit; if omitted, the AI agent uses its default editing prompt	--
`sessionId`	string	No	Session ID for correlating multiple edits in a conversation; `null` starts a new session	--
`requestId`	string	No	Pre-generated request ID; usually omitted so the server generates one	--
`waitForResult`	boolean	No	When `true`, the call blocks until editing completes and returns the result synchronously; default is `false`	Default: `false`

Exactly one identity source must be provided: emergencyOperationPlanId/emergencyOperationPlan, emergencyOperationPlanConfigurationId/emergencyOperationPlanConfiguration, or eopMasterCopyId/emergencyOperationPlanMasterCopy. District/organization details are resolved only from the explicit organizationId on the selected request object; the workflow no longer discovers organization IDs indirectly from EOP, configuration, or Master Copy IDs.

Response (Async -- waitForResult: false)

{
  "requestId": "req-7f3a2b1c-d4e5-6789-abcd-ef0123456789",
  "sessionId": "sess-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "accepted",
  "message": "Editing job accepted and queued for processing",
  "workflowRunId": "wf-run-9e8d7c6b-5a4f-3210-fedc-ba9876543210"
}

Response (Sync -- waitForResult: true)

{
  "requestId": "req-7f3a2b1c-d4e5-6789-abcd-ef0123456789",
  "sessionId": "sess-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "success",
  "message": "Edit completed successfully",
  "isEdit": true,
  "responseStatus": "success",
  "agentResponse": {
    "text": "<p>Current evacuation procedures for the main building.</p><p>After confirming all rooms are clear, verify assembly point headcount against the roster before releasing the all-clear signal.</p>"
  }
}

Response Fields

Field	Type	Description
`requestId`	string	Unique identifier for this editing job
`sessionId`	string	Session identifier; pass this to subsequent edits for conversation continuity
`status`	string	`accepted` (async) or `success` / `error` (sync)
`message`	string	Human-readable status message
`workflowRunId`	string	Workflow execution identifier (async mode only)
`isEdit`	boolean	Whether the response represents an edit operation (sync mode only)
`responseStatus`	string	Final processing status (sync mode only)
`agentResponse`	object	Contains the AI-generated output (sync mode only)
`agentResponse.text`	string	The edited HTML content returned by the AI agent

Error Responses

HTTP Status	Condition
400	None or more than one of `emergencyOperationPlanId`/`emergencyOperationPlan`, `emergencyOperationPlanConfigurationId`/`emergencyOperationPlanConfiguration`, and `eopMasterCopyId`/`emergencyOperationPlanMasterCopy` provided, or missing/invalid `userId` or `roleId`
401	Invalid or expired bearer token or missing subscription key
404	Specified EOP plan not found
429	Rate limit exceeded
500	Internal processing error

curl Example (using emergencyOperationPlan object)

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"},
      "userId": "user-456",
      "roleId": "safety-coordinator",
      "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"
    }
  }'

curl Example (using emergencyOperationPlanConfiguration object)

Use this variant for pre-EOP configuration-stage plans where the frontend sends configuration identity plus explicit organization context.

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": {
      "emergencyOperationPlanConfiguration": {"id": "config-xyz789", "organizationId": "org-789"},
      "userId": "user-456",
      "roleId": "safety-coordinator",
      "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"
    }
  }'

k12-annex-editing-status

Check the current status of one or more EOP annex editing jobs.

Property	Value
Endpoint	`POST /ai/api/tools/k12-annex-editing-status/execute`
Content-Type	`application/json`

Request

{
  "data": {
    "requestIds": ["req-7f3a2b1c-d4e5-6789-abcd-ef0123456789"]
  }
}

Request Fields

Field	Type	Required	Description	Constraints
`requestIds`	array of strings	Yes	One or more request IDs to check	Each string minimum 1 character

Response

[
  {
    "requestId": "req-7f3a2b1c-d4e5-6789-abcd-ef0123456789",
    "sessionId": "sess-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "processing"
  }
]

Response Fields

The response is an array with one entry per requested ID:

Field	Type	Description
`requestId`	string	The request ID that was queried
`sessionId`	string	Associated session identifier
`status`	string	Current status: `accepted`, `processing`, `success`, `error`, or `cancelled`

Error Responses

HTTP Status	Condition
400	`requestIds` is missing, empty, or contains empty strings
401	Invalid or expired bearer token or missing subscription key
429	Rate limit exceeded

curl Example

curl -X POST "https://dev-k12-aitools-t27p-apim.azure-api.net/ai/api/tools/k12-annex-editing-status/execute" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Ocp-Apim-Subscription-Key: $SUBSCRIPTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "requestIds": ["req-7f3a2b1c-d4e5-6789-abcd-ef0123456789"]
    }
  }'

k12-annex-editing-result

Fetch the final result of a completed EOP annex editing job.

Property	Value
Endpoint	`POST /ai/api/tools/k12-annex-editing-result/execute`
Content-Type	`application/json`

Request

{
  "data": {
    "requestId": "req-7f3a2b1c-d4e5-6789-abcd-ef0123456789"
  }
}

Request Fields

Field	Type	Required	Description	Constraints
`requestId`	string	Yes	The editing job request ID	Minimum 1 character

Response (Success)

{
  "requestId": "req-7f3a2b1c-d4e5-6789-abcd-ef0123456789",
  "sessionId": "sess-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "success",
  "message": "<p>Current evacuation procedures for the main building.</p><p>After confirming all rooms are clear, verify assembly point headcount against the roster before releasing the all-clear signal.</p>",
  "isEdit": true
}

Response (Error)

{
  "requestId": "req-7f3a2b1c-d4e5-6789-abcd-ef0123456789",
  "sessionId": "sess-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "error",
  "message": "AI processing failed: unable to generate edited content"
}

Response Fields

Field	Type	Description
`requestId`	string	The editing job request ID
`sessionId`	string	Associated session identifier
`status`	string	Terminal status: `success` or `error`
`message`	string	On success: the edited HTML content. On error: a description of the failure.
`isEdit`	boolean	`true` when the response contains edited content

Error Responses

HTTP Status	Condition
400	`requestId` is missing or empty
401	Invalid or expired bearer token or missing subscription key
404	No result found for the specified request ID
429	Rate limit exceeded

curl Example

curl -X POST "https://dev-k12-aitools-t27p-apim.azure-api.net/ai/api/tools/k12-annex-editing-result/execute" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Ocp-Apim-Subscription-Key: $SUBSCRIPTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "requestId": "req-7f3a2b1c-d4e5-6789-abcd-ef0123456789"
    }
  }'

QRG Generation Tools

k12-qrg-generation-kickoff

Start QRG generation from an Emergency Operation Plan. The system processes each annex in the EOP, classifies it, identifies target roles, and generates structured Quick Reference Guides.

Property	Value
Endpoint	`POST /ai/api/tools/k12-qrg-generation-kickoff/execute`
Content-Type	`application/json`

Request

{
  "data": {
    "emergencyOperationPlanId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "generalUserTagIds": ["d4e5f6a7-b8c9-0123-defg-456789abcdef", "e5f6a7b8-c9d0-1234-efgh-56789abcdef0"],
    "sessionId": null,
    "waitForResult": false
  }
}

Request Fields

Field	Type	Required	Description	Constraints
`emergencyOperationPlanId`	string	Yes	UUID of the Emergency Operation Plan to generate QRGs from	Valid UUID format
`generalUserTagIds`	array of strings	No	Filter generation to specific role tags; if omitted, all EOP roles are used	Each entry must be a valid UUID
`sessionId`	string	No	Session identifier for grouping related operations; `null` starts a new session	--
`requestId`	string	No	Pre-generated request ID; usually omitted so the server generates one	--
`waitForResult`	boolean	No	When `true`, blocks until generation completes and returns the full result	Default: `false`

Response (Async -- status: accepted)

{
  "requestId": "gen-b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "sessionId": "sess-c3d4e5f6-a7b8-9012-cdef-0123456789ab",
  "status": "accepted",
  "message": "QRG generation accepted and queued for processing"
}

Response (Sync -- status: success)

Note: The kickoff endpoint (both sync and async) always returns lowercase status values (accepted, success, error). The status polling and result endpoints return UPPERCASE values (PROCESSING, SUCCESS, ERROR, CANCELLED).

{
  "requestId": "gen-b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "sessionId": "sess-c3d4e5f6-a7b8-9012-cdef-0123456789ab",
  "status": "success",
  "data": {
    "root": [
      {
        "name": "Fire Safety - Teachers",
        "organizationId": "org-d4e5f6a7-b8c9-0123-4567-89abcdef0123",
        "type": "EMERGENCY",
        "functionality": null,
        "hazard": "FIRE",
        "generalUserTagManagementType": "ASSIGN_SELECTED",
        "generalUserTagIds": ["d4e5f6a7-b8c9-0123-defg-456789abcdef"],
        "contentBlocks": [
          {
            "type": "BEFORE",
            "content": "<ul><li>Know the location of fire extinguishers and pull stations</li><li>Review evacuation routes posted in each classroom</li><li>Verify emergency contact lists are current</li></ul>"
          },
          {
            "type": "DURING",
            "content": "<ul><li>Activate the nearest fire alarm pull station</li><li>Direct students to exit via the designated evacuation route</li><li>Close classroom doors and windows when leaving</li><li>Take attendance roster and student medications</li></ul>"
          },
          {
            "type": "AFTER",
            "content": "<ul><li>Account for all students at the assembly point</li><li>Report any missing students to the incident commander</li><li>Do not re-enter the building until authorized</li><li>Document the incident for administrative review</li></ul>"
          }
        ]
      }
    ]
  }
}

Response Fields (Accepted)

Field	Type	Description
`requestId`	string	Unique identifier for this generation job
`sessionId`	string	Session identifier
`status`	string	`accepted`
`message`	string	Confirmation message

Response Fields (Success Result)

Field	Type	Description
`requestId`	string	The generation job request ID
`sessionId`	string	Session identifier
`status`	string	`SUCCESS`
`data`	object	Container for generated QRGs
`data.root`	array	List of generated QRG objects

Each QRG object in data.root:

Field	Type	Description
`name`	string	Display name for the QRG (max 200 characters)
`organizationId`	string	Organization this QRG belongs to
`type`	string	QRG category: `FUNCTIONAL` or `EMERGENCY`
`functionality`	string or null	Functional category (e.g., `EVACUATION`, `LOCKDOWN`, `SHELTER_IN_PLACE`) when type is `FUNCTIONAL`; null for emergency types
`hazard`	string or null	Hazard category (e.g., `FIRE`, `ACTIVE_SHOOTER`, `TORNADO`) when type is `EMERGENCY`; null for functional types
`generalUserTagManagementType`	string	Role assignment mode: `ASSIGN_SELECTED` or `ASSIGN_ALL`
`generalUserTagIds`	array of strings	Assigned role tag UUIDs
`contentBlocks`	array	QRG content organized by phase
`contentBlocks[].type`	string	Phase: `BEFORE`, `DURING`, or `AFTER`
`contentBlocks[].content`	string	HTML content for this phase

Response (Error)

{
  "requestId": "gen-b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "sessionId": "sess-c3d4e5f6-a7b8-9012-cdef-0123456789ab",
  "status": "ERROR",
  "message": "AI processing failed: 6/6 annexes failed AI classification",
  "errors": [
    "[classify:Fire Safety Annex] AI classification failed: PermissionDenied",
    "[classify:Tornado Annex] AI classification failed: PermissionDenied"
  ]
}

Error Responses

HTTP Status	Condition
400	Missing or invalid `emergencyOperationPlanId`
401	Invalid or expired bearer token or missing subscription key
404	EOP plan not found
429	Rate limit exceeded
500	Internal processing error

curl Example

curl -X POST "https://dev-k12-aitools-t27p-apim.azure-api.net/ai/api/tools/k12-qrg-generation-kickoff/execute" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Ocp-Apim-Subscription-Key: $SUBSCRIPTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "emergencyOperationPlanId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "generalUserTagIds": ["d4e5f6a7-b8c9-0123-defg-456789abcdef"],
      "waitForResult": false
    }
  }'

k12-qrg-generation-status

Check the status of one or more QRG generation jobs.

Property	Value
Endpoint	`POST /ai/api/tools/k12-qrg-generation-status/execute`
Content-Type	`application/json`

Request

{
  "data": {
    "requestIds": ["gen-b2c3d4e5-f6a7-8901-bcde-f12345678901"]
  }
}

Request Fields

Field	Type	Required	Description	Constraints
`requestIds`	array of strings	Yes	One or more generation job request IDs to check	Each string minimum 1 character

Response

[
  {
    "requestId": "gen-b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "sessionId": "sess-c3d4e5f6-a7b8-9012-cdef-0123456789ab",
    "status": "PROCESSING",
    "message": "Processing annex 3 of 6"
  }
]

Response Fields

The response is an array with one entry per requested ID:

Field	Type	Description
`requestId`	string	The request ID that was queried
`sessionId`	string	Associated session identifier
`status`	string	Current status: `accepted`, `PROCESSING`, `SUCCESS`, `ERROR`, or `CANCELLED`
`message`	string	Optional progress or status detail

note

QRG generation statuses use uppercase values (PROCESSING, SUCCESS, ERROR, CANCELLED). The initial acceptance status is lowercase accepted.

Error Responses

HTTP Status	Condition
400	`requestIds` is missing, empty, or contains empty strings
401	Invalid or expired bearer token or missing subscription key
429	Rate limit exceeded

curl Example

curl -X POST "https://dev-k12-aitools-t27p-apim.azure-api.net/ai/api/tools/k12-qrg-generation-status/execute" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Ocp-Apim-Subscription-Key: $SUBSCRIPTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "requestIds": ["gen-b2c3d4e5-f6a7-8901-bcde-f12345678901"]
    }
  }'

k12-qrg-generation-result

Fetch the full result of a completed QRG generation job, including all generated QRGs and processing statistics.

Property	Value
Endpoint	`POST /ai/api/tools/k12-qrg-generation-result/execute`
Content-Type	`application/json`

Request

{
  "data": {
    "requestId": "gen-b2c3d4e5-f6a7-8901-bcde-f12345678901"
  }
}

Request Fields

Field	Type	Required	Description	Constraints
`requestId`	string	Yes	The generation job request ID	Minimum 1 character

Response (SUCCESS)

{
  "requestId": "gen-b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "sessionId": "sess-c3d4e5f6-a7b8-9012-cdef-0123456789ab",
  "status": "SUCCESS",
  "data": {
    "root": [
      {
        "name": "Fire Safety - Teachers",
        "organizationId": "org-d4e5f6a7-b8c9-0123-4567-89abcdef0123",
        "type": "EMERGENCY",
        "functionality": null,
        "hazard": "FIRE",
        "generalUserTagManagementType": "ASSIGN_SELECTED",
        "generalUserTagIds": ["d4e5f6a7-b8c9-0123-defg-456789abcdef"],
        "contentBlocks": [
          {
            "type": "BEFORE",
            "content": "<ul><li>Know the location of fire extinguishers and pull stations</li></ul>"
          },
          {
            "type": "DURING",
            "content": "<ul><li>Activate the nearest fire alarm pull station</li><li>Direct students to evacuate via designated routes</li></ul>"
          },
          {
            "type": "AFTER",
            "content": "<ul><li>Account for all students at the assembly point</li><li>Report missing students to the incident commander</li></ul>"
          }
        ]
      }
    ]
  },
  "aiStats": {
    "totalAnnexes": 6,
    "aiClassifySuccess": 6,
    "aiClassifyError": 0,
    "aiGroupsSuccess": 6,
    "aiGroupsError": 0,
    "aiRolesSuccess": 6,
    "aiRolesError": 0,
    "aiGenerateSuccess": 12,
    "aiGenerateError": 0
  },
  "warning": null
}

Response (ERROR)

{
  "requestId": "gen-b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "sessionId": "sess-c3d4e5f6-a7b8-9012-cdef-0123456789ab",
  "status": "ERROR",
  "message": "AI processing failed: 6/6 annexes failed AI classification",
  "errors": [
    "[classify:Fire Safety Annex] AI classification failed: PermissionDenied",
    "[classify:Tornado Annex] AI classification failed: PermissionDenied"
  ],
  "aiStats": {
    "totalAnnexes": 6,
    "aiClassifySuccess": 0,
    "aiClassifyError": 6,
    "aiGroupsSuccess": 0,
    "aiGroupsError": 0,
    "aiRolesSuccess": 0,
    "aiRolesError": 0,
    "aiGenerateSuccess": 0,
    "aiGenerateError": 0
  }
}

Response (PROCESSING / CANCELLED)

{
  "requestId": "gen-b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "sessionId": "sess-c3d4e5f6-a7b8-9012-cdef-0123456789ab",
  "status": "PROCESSING"
}

{
  "requestId": "gen-b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "sessionId": "sess-c3d4e5f6-a7b8-9012-cdef-0123456789ab",
  "status": "CANCELLED"
}

Response Fields

Field	Type	Description
`requestId`	string	The generation job request ID
`sessionId`	string	Session identifier
`status`	string	`SUCCESS`, `ERROR`, `PROCESSING`, or `CANCELLED`
`data`	object	Present on `SUCCESS`; contains generated QRGs
`data.root`	array	List of generated QRG objects (see QRG object fields in the kickoff section)
`message`	string	Present on `ERROR`; describes the failure
`errors`	array of strings	Present on `ERROR`; individual error messages per annex or AI stage
`aiStats`	object	Processing statistics (present on `SUCCESS` and `ERROR`)
`warning`	string or null	Optional warning message for partial success scenarios

aiStats fields:

Field	Type	Description
`totalAnnexes`	number	Total number of annexes processed
`aiClassifySuccess`	number	Annexes successfully classified
`aiClassifyError`	number	Annexes that failed classification
`aiGroupsSuccess`	number	Annexes with successful group extraction
`aiGroupsError`	number	Annexes that failed group extraction
`aiRolesSuccess`	number	Annexes with successful role mapping
`aiRolesError`	number	Annexes that failed role mapping
`aiGenerateSuccess`	number	QRGs successfully generated
`aiGenerateError`	number	QRG generation failures

Error Responses

HTTP Status	Condition
400	`requestId` is missing or empty
401	Invalid or expired bearer token or missing subscription key
404	No result found for the specified request ID
429	Rate limit exceeded

curl Example

curl -X POST "https://dev-k12-aitools-t27p-apim.azure-api.net/ai/api/tools/k12-qrg-generation-result/execute" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Ocp-Apim-Subscription-Key: $SUBSCRIPTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "requestId": "gen-b2c3d4e5-f6a7-8901-bcde-f12345678901"
    }
  }'

QRG Editing Tools

k12-qrg-editing-kickoff

Start an AI-assisted edit of a specific section (BEFORE, DURING, or AFTER) within an existing Quick Reference Guide.

Property	Value
Endpoint	`POST /ai/api/tools/k12-qrg-editing-kickoff/execute`
Content-Type	`application/json`

Request

{
  "data": {
    "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "roleId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "section": "BEFORE",
    "content": "<ul><li>Know evacuation routes</li></ul>",
    "prompt": "Add a bullet about checking fire extinguisher locations",
    "sessionId": null,
    "quickReferenceGuide": {
      "name": "Fire Safety Procedures",
      "type": "FUNCTIONAL",
      "instructionFor": "FIRE",
      "generalUserTagManagementType": "ASSIGN_SELECTED",
      "generalUserTags": [
        {
          "label": "Teachers",
          "value": "c3d4e5f6-a7b8-9012-cdef-0123456789ab"
        }
      ],
      "organization": {
        "id": "d4e5f6a7-b8c9-0123-4567-89abcdef0123",
        "name": "Lincoln Elementary",
        "type": "FACILITY",
        "parent": {
          "id": "e5f6a7b8-c9d0-1234-5678-9abcdef01234",
          "name": "Springfield School District",
          "type": "DISTRICT"
        }
      }
    }
  }
}

Request Fields

Field	Type	Required	Description	Constraints
`userId`	string	Yes	UUID of the user initiating the edit	Valid UUID
`roleId`	string	Yes	UUID of the user's role	Valid UUID
`section`	string	Yes	Which QRG section to edit	`BEFORE`, `DURING`, or `AFTER`
`content`	string	Yes	Current HTML content of the section	--
`prompt`	string	Yes	Natural language instruction for the edit	Minimum 1 character
`sessionId`	string	No	Session UUID for conversation continuity; `null` starts a new session	Valid UUID if provided
`quickReferenceGuide`	object	Yes	Metadata about the QRG being edited	See nested fields below

quickReferenceGuide fields:

Field	Type	Required	Description	Constraints
`name`	string	Yes	Display name of the QRG	Maximum 200 characters
`type`	string	Yes	QRG category	`FUNCTIONAL` or `EMERGENCY`
`instructionFor`	string	Yes	Category label (e.g., `FIRE`, `EVACUATION`, `LOCKDOWN`)	Minimum 1 character
`generalUserTagManagementType`	string	Yes	How roles are assigned	`ASSIGN_SELECTED` or `ASSIGN_ALL`
`generalUserTags`	array	Yes	Role tags assigned to this QRG	Minimum 1 entry if `ASSIGN_SELECTED`
`generalUserTags[].label`	string	Yes	Role display name	--
`generalUserTags[].value`	string	No	Role tag UUID	Valid UUID if provided
`organization`	object	No	Facility and district context	See nested fields below

organization fields:

Field	Type	Required	Description	Constraints
`id`	string	Yes	Organization UUID	Valid UUID
`name`	string	Yes	Organization display name	--
`type`	string	Yes	Organization level	`FACILITY` or `DISTRICT`
`parent`	object	No	Parent district (required when type is `FACILITY`)	See nested fields below

parent fields:

Field	Type	Required	Description	Constraints
`id`	string	Yes	Parent district UUID	Valid UUID
`name`	string	Yes	District display name	--
`type`	string	Yes	Always `DISTRICT`	Literal: `DISTRICT`

Response (Accepted)

{
  "requestId": "edit-f6a7b8c9-d0e1-2345-fghi-6789abcdef01",
  "sessionId": "sess-a7b8c9d0-e1f2-3456-ghij-789abcdef012",
  "status": "accepted",
  "message": "QRG editing job accepted and queued for processing"
}

Response (Error)

{
  "requestId": "edit-f6a7b8c9-d0e1-2345-fghi-6789abcdef01",
  "sessionId": "sess-a7b8c9d0-e1f2-3456-ghij-789abcdef012",
  "status": "error",
  "message": "Validation failed: section must be BEFORE, DURING, or AFTER"
}

Response Fields

Field	Type	Description
`requestId`	string	Unique identifier for this editing job
`sessionId`	string	Session identifier for subsequent operations
`status`	string	`accepted` or `error`
`message`	string	Confirmation or error description

Error Responses

HTTP Status	Condition
400	Missing required field, invalid section value, or empty prompt
401	Invalid or expired bearer token or missing subscription key
429	Rate limit exceeded
500	Internal processing error

curl Example

curl -X POST "https://dev-k12-aitools-t27p-apim.azure-api.net/ai/api/tools/k12-qrg-editing-kickoff/execute" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Ocp-Apim-Subscription-Key: $SUBSCRIPTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "roleId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "section": "BEFORE",
      "content": "<ul><li>Know evacuation routes</li></ul>",
      "prompt": "Add a bullet about checking fire extinguisher locations",
      "quickReferenceGuide": {
        "name": "Fire Safety Procedures",
        "type": "FUNCTIONAL",
        "instructionFor": "FIRE",
        "generalUserTagManagementType": "ASSIGN_SELECTED",
        "generalUserTags": [
          { "label": "Teachers", "value": "c3d4e5f6-a7b8-9012-cdef-0123456789ab" }
        ],
        "organization": {
          "id": "d4e5f6a7-b8c9-0123-4567-89abcdef0123",
          "name": "Lincoln Elementary",
          "type": "FACILITY",
          "parent": {
            "id": "e5f6a7b8-c9d0-1234-5678-9abcdef01234",
            "name": "Springfield School District",
            "type": "DISTRICT"
          }
        }
      }
    }
  }'

k12-qrg-editing-status

Check the status of one or more QRG editing jobs.

Property	Value
Endpoint	`POST /ai/api/tools/k12-qrg-editing-status/execute`
Content-Type	`application/json`

Request

{
  "data": {
    "requestIds": ["edit-f6a7b8c9-d0e1-2345-fghi-6789abcdef01"]
  }
}

Request Fields

Field	Type	Required	Description	Constraints
`requestIds`	array of strings	Yes	One or more editing job request IDs to check	Each string minimum 1 character

Response

[
  {
    "requestId": "edit-f6a7b8c9-d0e1-2345-fghi-6789abcdef01",
    "sessionId": "sess-a7b8c9d0-e1f2-3456-ghij-789abcdef012",
    "status": "processing",
    "message": "AI agent is editing the BEFORE section"
  }
]

Response Fields

The response is an array with one entry per requested ID:

Field	Type	Description
`requestId`	string	The request ID that was queried
`sessionId`	string	Associated session identifier
`status`	string	Current status: `accepted`, `processing`, `success`, `error`, or `cancelled`
`message`	string	Optional progress detail

note

QRG editing statuses use lowercase values (processing, success, error, cancelled).

Error Responses

HTTP Status	Condition
400	`requestIds` is missing, empty, or contains empty strings
401	Invalid or expired bearer token or missing subscription key
429	Rate limit exceeded

curl Example

curl -X POST "https://dev-k12-aitools-t27p-apim.azure-api.net/ai/api/tools/k12-qrg-editing-status/execute" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Ocp-Apim-Subscription-Key: $SUBSCRIPTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "requestIds": ["edit-f6a7b8c9-d0e1-2345-fghi-6789abcdef01"]
    }
  }'

k12-qrg-editing-result

Fetch the result of a completed QRG editing job, including the AI-edited section content.

Property	Value
Endpoint	`POST /ai/api/tools/k12-qrg-editing-result/execute`
Content-Type	`application/json`

Request

{
  "data": {
    "requestId": "edit-f6a7b8c9-d0e1-2345-fghi-6789abcdef01"
  }
}

Request Fields

Field	Type	Required	Description	Constraints
`requestId`	string	Yes	The editing job request ID	Minimum 1 character

Response (Success)

{
  "requestId": "edit-f6a7b8c9-d0e1-2345-fghi-6789abcdef01",
  "sessionId": "sess-a7b8c9d0-e1f2-3456-ghij-789abcdef012",
  "status": "success",
  "message": "<ul><li>Know evacuation routes</li><li>Verify fire extinguisher locations in hallways and common areas</li></ul>",
  "isEdit": true
}

Response (Error)

{
  "requestId": "edit-f6a7b8c9-d0e1-2345-fghi-6789abcdef01",
  "sessionId": "sess-a7b8c9d0-e1f2-3456-ghij-789abcdef012",
  "status": "error",
  "message": "AI processing failed: unable to generate edited content for the BEFORE section"
}

Response (Processing / Accepted / Cancelled)

{
  "requestId": "edit-f6a7b8c9-d0e1-2345-fghi-6789abcdef01",
  "sessionId": "sess-a7b8c9d0-e1f2-3456-ghij-789abcdef012",
  "status": "processing",
  "message": "Edit is still in progress"
}

Response Fields

Field	Type	Description
`requestId`	string	The editing job request ID
`sessionId`	string	Associated session identifier
`status`	string	`success`, `error`, `processing`, `accepted`, or `cancelled`
`message`	string	On success: the edited HTML content. On error: a description of the failure. On other statuses: progress detail.
`isEdit`	boolean	`true` when the response contains edited content (present on `success` only)

Error Responses

HTTP Status	Condition
400	`requestId` is missing or empty
401	Invalid or expired bearer token or missing subscription key
404	No result found for the specified request ID
429	Rate limit exceeded

curl Example

curl -X POST "https://dev-k12-aitools-t27p-apim.azure-api.net/ai/api/tools/k12-qrg-editing-result/execute" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Ocp-Apim-Subscription-Key: $SUBSCRIPTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "requestId": "edit-f6a7b8c9-d0e1-2345-fghi-6789abcdef01"
    }
  }'

Cancellation

k12-cancel-task-request

Cancel a pending or in-progress EOP editing job. The tool marks the job as cancelled and stops further processing on a best-effort basis.

Property	Value
Endpoint	`POST /ai/api/tools/k12-cancel-task-request/execute`
Content-Type	`application/json`

Request

{
  "data": {
    "requestId": "req-7f3a2b1c-d4e5-6789-abcd-ef0123456789"
  }
}

Request Fields

Field	Type	Required	Description	Constraints
`requestId`	string	Yes	The request ID of the EOP editing job to cancel	Minimum 1 character
`dryRun`	boolean	No	When `true`, returns what would be cancelled without executing the cancellation	Default: `false`

Response (Success)

{
  "status": "success",
  "message": "Request cancelled successfully"
}

Response (Error)

{
  "status": "error",
  "message": "Request not found or already in a terminal state"
}

Response Fields

Field	Type	Description
`status`	string	`success` if cancellation was applied; `error` if the job could not be cancelled
`message`	string	Human-readable description of the outcome

Error Responses

HTTP Status	Condition
400	`requestId` is missing or empty
401	Invalid or expired bearer token or missing subscription key
404	No job found for the specified request ID
409	Job is already in a terminal state and cannot be cancelled
429	Rate limit exceeded

curl Example

curl -X POST "https://dev-k12-aitools-t27p-apim.azure-api.net/ai/api/tools/k12-cancel-task-request/execute" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Ocp-Apim-Subscription-Key: $SUBSCRIPTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "requestId": "req-7f3a2b1c-d4e5-6789-abcd-ef0123456789"
    }
  }'

note

Cancellation is best-effort. If the AI agent is mid-processing when cancellation is received, the current operation may complete before the job terminates. Always verify the final status via the status endpoint after issuing a cancel request.

k12-qrg-cancel

Cancel a pending or in-progress QRG generation or editing job. This tool covers both QRG Generation and QRG Editing workflows.

Property	Value
Endpoint	`POST /ai/api/tools/k12-qrg-cancel/execute`
Content-Type	`application/json`

Request

{
  "data": {
    "requestId": "gen-b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "jobType": "generation"
  }
}

Request Fields

Field	Type	Required	Description	Constraints
`requestId`	string	Yes	The request ID of the job to cancel	Minimum 1 character
`jobType`	string	No	Type of job to cancel	`generation` or `editing`; default: `generation`

Response (Success)

{
  "status": "success"
}

Response (Error)

{
  "status": "error"
}

Response Fields

Field	Type	Description
`status`	string	`success` if cancellation was applied; `error` if the job could not be cancelled (e.g., already completed or not found)

Error Responses

HTTP Status	Condition
400	`requestId` is missing or empty
401	Invalid or expired bearer token or missing subscription key
404	No job found for the specified request ID
409	Job is already in a terminal state and cannot be cancelled
429	Rate limit exceeded

curl Example

curl -X POST "https://dev-k12-aitools-t27p-apim.azure-api.net/ai/api/tools/k12-qrg-cancel/execute" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Ocp-Apim-Subscription-Key: $SUBSCRIPTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "requestId": "gen-b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "jobType": "generation"
    }
  }'

note

Cancellation is best-effort. If the AI pipeline is mid-step when cancellation is received, the current step may complete before the job terminates. Always verify the final status via the status endpoint after issuing a cancel request.

Status Convention Summary

Different tool families use different status casing. Your integration must normalize these values before comparison.

Tool Family	Status Convention	Values
EOP Editing (`k12-annex-editing-*`)	Lowercase	`accepted`, `processing`, `success`, `error`, `cancelled`
QRG Generation (`k12-qrg-generation-*`)	Uppercase	`accepted`, `PROCESSING`, `SUCCESS`, `ERROR`, `CANCELLED`
QRG Editing (`k12-qrg-editing-*`)	Lowercase	`accepted`, `processing`, `success`, `error`, `cancelled`
EOP Cancel (`k12-cancel-task-request`)	Lowercase	`success`, `error`
QRG Cancel (`k12-qrg-cancel`)	Lowercase	`success`, `error`

note

The initial accepted status from kickoff tools is always lowercase across all families. Only subsequent statuses differ in casing.

Next Steps

Endpoint Reference

Authentication, base URLs, and the async integration pattern

QRG Generation Deep Dive

Detailed walkthrough of the QRG generation pipeline and AI processing stages

EOP Editing Tools

k12-annex-editing-kickoff​

Request​

Request Fields​

Response (Async -- waitForResult: false)​

Response (Sync -- waitForResult: true)​

Response Fields​

Error Responses​

curl Example (using emergencyOperationPlan object)​

curl Example (using emergencyOperationPlanConfiguration object)​

k12-annex-editing-status​

Request​

Request Fields​

Response​

Response Fields​

Error Responses​

curl Example​

k12-annex-editing-result​

Request​

Request Fields​

Response (Success)​

Response (Error)​

Response Fields​

Error Responses​

curl Example​

QRG Generation Tools

k12-qrg-generation-kickoff​

Request​

Request Fields​

Response (Async -- status: accepted)​

Response (Sync -- status: success)​

Response Fields (Accepted)​

Response Fields (Success Result)​

Response (Error)​

Error Responses​

curl Example​

k12-qrg-generation-status​

Request​

Request Fields​

Response​

Response Fields​

Error Responses​

curl Example​

k12-qrg-generation-result​

Request​

Request Fields​

Response (SUCCESS)​

Response (ERROR)​

Response (PROCESSING / CANCELLED)​

Response Fields​

Error Responses​

curl Example​

QRG Editing Tools

k12-qrg-editing-kickoff​

Request​

Request Fields​

Response (Accepted)​

Response (Error)​

Response Fields​

Error Responses​

curl Example​

k12-qrg-editing-status​

Request​

Request Fields​

Response​

Response Fields​

Error Responses​

curl Example​

k12-qrg-editing-result​

Request​

Request Fields​

Response (Success)​

Response (Error)​

Response (Processing / Accepted / Cancelled)​

Response Fields​

Error Responses​

curl Example​

Cancellation

k12-cancel-task-request​

Request​

k12-annex-editing-kickoff

Request

Request Fields

Response (Async -- waitForResult: false)

Response (Sync -- waitForResult: true)

Response Fields

Error Responses

curl Example (using emergencyOperationPlan object)

curl Example (using emergencyOperationPlanConfiguration object)

k12-annex-editing-status

Request

Request Fields

Response

Response Fields

Error Responses

curl Example

k12-annex-editing-result

Request

Request Fields

Response (Success)

Response (Error)

Response Fields

Error Responses

curl Example

k12-qrg-generation-kickoff

Request

Request Fields

Response (Async -- status: accepted)

Response (Sync -- status: success)

Response Fields (Accepted)

Response Fields (Success Result)

Response (Error)

Error Responses

curl Example

k12-qrg-generation-status

Request

Request Fields

Response

Response Fields

Error Responses

curl Example

k12-qrg-generation-result

Request

Request Fields

Response (SUCCESS)

Response (ERROR)

Response (PROCESSING / CANCELLED)

Response Fields

Error Responses

curl Example

k12-qrg-editing-kickoff

Request

Request Fields

Response (Accepted)

Response (Error)

Response Fields

Error Responses

curl Example

k12-qrg-editing-status

Request

Request Fields

Response

Response Fields

Error Responses

curl Example

k12-qrg-editing-result

Request

Request Fields

Response (Success)

Response (Error)

Response (Processing / Accepted / Cancelled)

Response Fields

Error Responses

curl Example

k12-cancel-task-request

Request

Request Fields

Response (Success)

Response (Error)

Response Fields