Instructions

Scope Model

Math AI supports instruction bindings across curriculum scopes such as global, course, subject, lesson, and section. Global instructions are included down the hierarchy when scope composition is resolved.

This endpoint is meant for inspection and transparency. Normal chat usage does not require tenants to send instruction scope manually, because chat requests already resolve the effective prompt internally from the selected subject and its inherited bindings.

• Use this endpoint to inspect effective prompts at a given scope

• Use scope_id when the selected scope level requires a concrete record

• Expect prompt composition to include global bindings automatically

• Treat this as read-only from the external API point of view; instruction authoring remains managed on the Math AI side

Supported Scopes

The external inspection endpoint supports structural scopes, plus text-based scopes for special prompt segmentation.

• global: no scope_id required

• course: requires scope_id

• subject: requires scope_id

• lesson: requires scope_id

• section: requires scope_id

• assessment: requires scope_id

• topic: requires scope_text

• grade_band: requires scope_text

How This Relates To Chat

During normal tenant integration, you usually fetch subjects first, create a subject-bound chat, and let Math AI resolve global plus structural instruction bindings internally. The /instructions endpoints are mainly useful when a developer wants to inspect what effective prompt composition applies at a scope before or during integration work.

Normal chat flow:
GET /subjects -> POST /chats -> POST /chats/{chatId}/messages

Instruction inspection flow:
GET /instructions/global
GET /instructions/subject?scope_id=<subject_id>

Inspect Instruction Composition

curl -X GET "https://{{domain}}/api/external/v1/instructions/global" \
  -H "Authorization: Bearer <your_api_key>"

curl -X GET "https://{{domain}}/api/external/v1/instructions/subject?scope_id=<subject_id>" \
  -H "Authorization: Bearer <your_api_key>"

curl -X GET "https://{{domain}}/api/external/v1/instructions/topic?scope_text=fractions" \
  -H "Authorization: Bearer <your_api_key>"