> For the complete documentation index, see [llms.txt](https://developerdocs.instructure.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developerdocs.instructure.com/services/mastery-connect/key-concepts.md). # Key Concepts How MasteryConnect's entities relate — and the distinctions that will trip you up if you assume the endpoint names mean what they usually mean. MasteryConnect is a standards-based assessment platform: teachers deliver assessments, and the platform tracks each student's mastery of the standards those assessments measure. The API exposes that structure directly, so it helps to know the shape before you start querying. ## Everything Is District-Scoped A credential belongs to exactly one district, and the district is resolved from the token on the server — never from anything you send. There is no request parameter that can widen the scope. The practical consequences: * `GET /api/v2/districts` returns exactly one district: yours. * An id belonging to another district returns `404 Not Found`, not `403`. The API does not confirm that the record exists elsewhere. * You cannot query across districts, even if your organisation operates several. Each needs its own credential. ## The Organisational Hierarchy ``` District └── School ├── Section (the roster that comes from your SIS) └── Classroom (the mastery tracker teachers actually work in) └── Student ``` ### Section vs. Classroom This is the distinction most integrations get wrong first. | | Section | Classroom | | ---------- | ----------------------------- | ------------------------------- | | Origin | Synced from your SIS | Created in MasteryConnect | | Represents | The official course roster | A teacher's mastery tracker | | Analogue | "Period 3 Biology" in the SIS | The gradebook the teacher opens | A Section is the SIS's view of a group of students. A Classroom is the MasteryConnect tracker a teacher assesses against. They usually correspond, but they are separate records with separate ids, and one Section can back more than one Classroom. **Assessment data hangs off the Classroom, not the Section.** {% hint style="warning" %} A "tracker" is a Classroom. The `/api/v2/trackers/{tracker_id}/assessments` endpoint takes a **classroom id** as `tracker_id` — the two words name the same record. There is deliberately no top-level `/api/v2/trackers` collection; list classrooms via `/api/v2/classrooms` instead. {% endhint %} ### Kid vs. Student Both words appear in MasteryConnect, and they are not synonyms: * A **Kid** is the person's account at the school — one per learner. * A **Student** is that person's enrolment in one classroom. So one Kid has many Students: a learner in six classrooms is one Kid and six Student records. When you are joining data, the Kid is the stable identity of a person; the Student is a person-in-a-classroom. ## The Assessment Hierarchy ``` Material (the template — an assessment as authored) └── Assessment (a delivered copy of that template) └── Item (one question as it appears on that assessment) └── Score (one student's result on that item) ``` ### Material vs. Assessment A **Material** is the reusable template: the assessment as it was written. An **Assessment** is a copy of that template delivered to a specific classroom. Deliver one Material to five classrooms and you get one Material and five Assessments. Edit the Material afterwards and the already-delivered Assessments do not change — they are snapshots, which is what makes historical results trustworthy. Query Materials when you care about what was authored. Query Assessments when you care about what students actually took. ### Items and Questions An **Item** is a question in the context of one assessment — it carries the position, the point value, and the standard alignment for that assessment. The underlying **Question** (stem, type, depth of knowledge) lives in an item bank and can be reused across many Items. ## Standards and Objectives A **standard** is called an **Objective** throughout the API. Objectives are the learning targets that assessments measure and mastery is reported against. * An Objective can be attached to a Material, an Item, or a Classroom. * A **Class Objective** is an Objective tracked for a particular classroom — the standards that classroom is working on. * A **Curriculum Map** organises Objectives and Materials into a planned sequence, typically a scope-and-sequence for a course. * A **Pathway** groups Objectives for a subject into a progression. ## Item Banks An **Item Bank** is a collection of reusable Questions, and the Passages (reading passages, stimuli) those Questions refer to. Banks are the source authors draw on when building a Material. ``` Bank ├── Question └── Passage ``` ## Read-Only, By Design The API serves `GET` requests only. There is no endpoint that creates, updates or deletes anything, and no scope that grants write access. It is built for extracting data into your own systems, not for driving MasteryConnect from outside. ## What Is Deliberately Absent Some data is withheld regardless of the scopes you hold: * **Answer keys and correct answers.** Reports tell you how many students got an item right; they never tell you what the right answer was. * **Individual student responses.** * **SIS identifiers** on sections (`sis_id`, `lms_sis_id`). If your integration needs any of these, talk to Instructure Support rather than looking for an undocumented parameter — there isn't one. ## Next * [Getting Started](/services/mastery-connect/getting-started.md) — get a token, make a call. * [Conventions](/services/mastery-connect/conventions.md) — how every response is shaped. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developerdocs.instructure.com/services/mastery-connect/key-concepts.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.