> 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/getting-started.md).

# Getting Started

From credentials to your first successful call.

This walkthrough takes you from a fresh credential to reading real data. It assumes you can run `curl`; every call translates directly to any HTTP client.

## Prerequisites

Two things must be true before any call will succeed:

1. **The API is enabled for your district.** This is switched on by Instructure, not by you. It requires both a platform-level flag and a per-district setting; until both are on, every request returns `403 feature_disabled` even with a perfectly valid token.
2. **You have credentials with the scopes you need.** See [Authentication](/services/mastery-connect/authentication.md#getting-credentials).

Contact your MasteryConnect representative or Instructure Support to arrange both. Mention which data you intend to read so the right [scopes](/services/mastery-connect/authentication.md#scopes) get granted.

## Step 1 — Get a Token

```bash
curl -X POST https://api.masteryconnect.com/api/v2/token \
  -H 'Content-Type: application/json' \
  -d '{
        "grant_type": "client_credentials",
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET"
      }'
```

```json
{
  "access_token": "mc2_a1b2c3d4e5f6...",
  "token_type": "Bearer",
  "scope": "districts:read schools:read classrooms:read",
  "expires_in": 7200
}
```

Save the token to a shell variable for the rest of this guide:

```bash
export MC_TOKEN='mc2_a1b2c3d4e5f6...'
```

## Step 2 — Confirm It Works

The districts endpoint is the cheapest way to verify everything is wired up. It returns exactly one district — yours.

```bash
curl https://api.masteryconnect.com/api/v2/districts \
  -H "Authorization: Bearer $MC_TOKEN"
```

```json
{
  "data": [
    {
      "id": "1234",
      "type": "district",
      "attributes": {
        "name": "Example Unified School District",
        "created_at": "2019-08-14T09:12:44.000Z"
      }
    }
  ],
  "meta": { "total_count": 1, "total_pages": 1, "page": 1, "page_size": 25 },
  "links": { "first": "...", "last": "..." }
}
```

A `200` here means credentials, enablement and scopes are all good. Note your district id — nested routes need it.

{% hint style="warning" %}
If this returns `403 feature_disabled`, your credentials are fine but the API is not switched on for the district yet. That is a Support request, not a code problem.
{% endhint %}

## Step 3 — Walk Down the Hierarchy

List the district's schools, substituting the id from Step 2:

```bash
curl "https://api.masteryconnect.com/api/v2/districts/1234/schools?page[size]=5" \
  -H "Authorization: Bearer $MC_TOKEN"
```

Then the classrooms in one of those schools, newest first:

```bash
curl "https://api.masteryconnect.com/api/v2/classrooms?filter[school_id]=5678&sort=-created_at" \
  -H "Authorization: Bearer $MC_TOKEN"
```

Both endpoints support the same [pagination, filtering and sorting](/services/mastery-connect/conventions.md) parameters.

## Step 4 — Read Assessment Data

A classroom is also a "tracker" — the same record under a different name. Use a classroom id from Step 3 to list what that classroom has been assessed on:

```bash
curl "https://api.masteryconnect.com/api/v2/trackers/9012/assessments" \
  -H "Authorization: Bearer $MC_TOKEN"
```

For per-item performance on those assessments, use the [item analysis report](/services/mastery-connect/reports.md#item-analysis):

```bash
curl "https://api.masteryconnect.com/api/v2/reports/item_analysis?filter[classroom_id]=9012" \
  -H "Authorization: Bearer $MC_TOKEN"
```

## Step 5 — Page Through Everything

Most real integrations need every record, not the first 25. Follow `links.next` until it is absent:

```bash
#!/usr/bin/env bash
# Fetch every classroom in the district, one page at a time.
url="https://api.masteryconnect.com/api/v2/classrooms?page[size]=100"

while [ -n "$url" ]; do
  body=$(curl -sS -H "Authorization: Bearer $MC_TOKEN" "$url")
  echo "$body" | jq -c '.data[]'
  url=$(echo "$body" | jq -r '.links.next // empty')
done
```

`links.next` is omitted on the final page, which ends the loop. Use the maximum page size of 100 to minimise round trips — see [Rate Limits](/services/mastery-connect/limits-policies.md).

## A Realistic Sync

Fetching everything on every run wastes your request budget. For resources that support it, ask only for what changed:

```bash
curl "https://api.masteryconnect.com/api/v2/materials?filter[updated_since]=2026-09-01T00:00:00Z" \
  -H "Authorization: Bearer $MC_TOKEN"
```

Record the time you started each run and use it as the next run's `updated_since`. Not every resource supports this filter — check [Conventions](/services/mastery-connect/conventions.md#filtering-by-modification-time).

## Common First Problems

| Symptom                        | Likely cause                                                                 |
| ------------------------------ | ---------------------------------------------------------------------------- |
| `403 feature_disabled`         | API not enabled for the district. Contact Support.                           |
| `403 insufficient_scope`       | Credential lacks the scope. On nested routes you need the **child's** scope. |
| `401 invalid_token`            | Token expired (2h), revoked, or the header is not `Bearer <token>`.          |
| `404` on an id you know exists | The record belongs to another district.                                      |
| `422 Unknown filter '...'`     | Filters are allow-listed per endpoint; check the reference.                  |
| `429`                          | Slow down, honour `Retry-After`, and raise `page[size]` to 100.              |

## Next

* [Conventions](/services/mastery-connect/conventions.md) — envelope, pagination, filtering, sorting.
* [Errors](/services/mastery-connect/errors.md) — every error code and how to react.
* [API Reference](/services/mastery-connect/openapi.md) — all endpoints, try them in the browser.


---

# 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/getting-started.md?ask=<question>&goal=<endgoal>
```

`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.