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.

Contact your MasteryConnect representative or Instructure Support to arrange both. Mention which data you intend to read so the right scopes get granted.

Step 1 — Get a Token

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"
      }'

{
  "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:

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.

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

{
  "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.

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.

Step 3 — Walk Down the Hierarchy

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

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:

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 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:

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:

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:

#!/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.

A Realistic Sync

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

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.

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 — envelope, pagination, filtering, sorting.

• Errors — every error code and how to react.

• API Reference — all endpoints, try them in the browser.