The REST API.

Reading for a route-specific collection name is the single most likely way to build a client that reports success while syncing nothing: a missing key reads as an empty page, not as an error. Write one pager and reuse it everywhere.

# --data-urlencode, not -d: the scope list contains spaces, and a raw space in an
# x-www-form-urlencoded body is not something to leave to the server's goodwill.
TOKEN=$(curl -s "https://scolavo-auth.auth.us-east-1.amazoncognito.com/oauth2/token" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "scope=scolavo-mcp/content.read scolavo-mcp/content.export scolavo-mcp/media.download" \
  | jq -r .access_token)

curl -s --compressed "https://mcp.scolavo.com/v1/license" -H "Authorization: Bearer $TOKEN" | jq

{
  "orgId": "org-453b2b2bdf",
  "orgName": "Example Partner",
  "tier": "commercial",
  "status": "active",
  "contentGrants": ["college", "topics/ai-and-llms"],
  "quota": {
    "calls":         { "used": 1204, "limit": 500000 },
    "downloads":     { "used": 8810, "limit": 50000 },
    "exports":       { "used": 12,   "limit": 200 },
    "testprepitems": { "used": 0,    "limit": null }
  },
  "rateLimits": { "callsPerHour": null, "lessonReadsPerHour": 500, "urlMintsPerHour": 200 },
  "resetsAt": "2026-09-01T00:00:00.000Z",
  "eclaVersion": 1,
  "requiredEclaVersion": 1,
  "renewsAt": "2027-01-01T00:00:00Z",
  "contentVersion": "2026-08-04+4fd77ddd",
  "licenseUrl": "https://www.scolavo.com/legal/ecla"
}

Every content response also carries contentVersion and a lean licence envelope _license: {lic, tag}. tag is a forensic marker identifying org and scope: keep it if you persist our content, and expect it to be how a leak is traced back.

Two more strict enums: type (video|audio|image) on the media route and format (zip_url|inline) on the export routes. q is required on /v1/search and capped at 200 characters. Slugs are matched exactly — there is no fuzzy matching here, because code does not guess.

for each subject:                       125 calls   (outline)
  for each class:                     3,680 calls   (lesson)
    GET …/media?limit=100             3,680 calls   (asset list — at the default limit=25
                                                       a 31-asset class costs two calls)
      for each asset: mint one URL  113,844 calls   ← the N+1
                                    ─────────────
                                    121,329 calls, ~198 MB

It also burns 7,360 lesson-read units. At a typical lessonReadsPerHour of 500 that is a 15-hour floor before quota even enters the picture — and a full-corpus lesson walk trips the enumeration alarm, which auto-suspends the org and needs a human to reinstate it.

GET /v1/license                              1 call  (unmetered) — read contentVersion
for each subject:
  GET /v1/exports/subjects/{slug}          125 calls — a zip: every class, every transcript,
                                                        the manifest and the media manifest
POST /v1/media/urls  (100 ids per call)  1,139 calls — only for assets you will actually fetch
                                        ────────────
                                          1,264 metered calls

121,329 → 1,264 calls: 99.0% fewer requests, and zero lesson-read pressure — an export is not a lesson read, so the hourly velocity cap and the enumeration alarm never enter it. The trade is honest and small: an export bills one download per class, so the bulk path spends 3,680 extra download units — 3.2% more content quota to remove 99% of the calls.

# One subject, everything in it, one call.
URL=$(curl -s --compressed "https://mcp.scolavo.com/v1/exports/subjects/ai-and-llms" \
  -H "Authorization: Bearer $TOKEN" | jq -r .url)
curl -sL "$URL" -o ai-and-llms.zip          # the URL is signed and lives <= 15 min

# Batch-mint, 100 ids per call, only for assets you will actually fetch.
curl -s --compressed -X POST "https://mcp.scolavo.com/v1/media/urls" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"mediaIds":["topics/ai-and-llms/1#definition#video",
                   "topics/ai-and-llms/1#definition#audio"],"expiresIn":900}'

# Re-sync: send back the validator you stored.
curl -s -o /dev/null -w '%{http_code}\n' \
  "https://mcp.scolavo.com/v1/subjects?detail=brief" \
  -H "Authorization: Bearer $TOKEN" -H 'If-None-Match: "8f2c…"'
# 304

A plan with 5,000 monthly downloads and 50 monthly exports cannot afford the first row even once.

br is offered too and is 1–3 points better on this corpus, but it is used only if you name it: Accept-Encoding: * resolves to gzip, because “anything I did not list” is not the same sentence as “I can decode brotli”. identity and gzip;q=0 are honoured as the refusals they are, and q-values are read as a real negotiation rather than a substring match.

curl -s --compressed -o /dev/null -w 'wire bytes: %{size_download}\n' \
  "https://mcp.scolavo.com/v1/subjects?detail=full&limit=100" -H "Authorization: Bearer $TOKEN"
# wire bytes: 14856      (101,426 uncompressed)

{"error":{"code":"CONTENT_NOT_GRANTED","message":"…","grant":"topics/ai-and-llms","requestId":"…"}}

Extra keys are per-code and additive: parameter, allowed, received, min/max, grant, tiers, allow, retryAfterSeconds, quotaResetsAt, hint. requestId is also the x-request-id header on every response — quote it to support. The complete list of codes is published as an enum in the schema (components.schemas.Error), and a drift test asserts that every code the router can put on the wire appears there, so a generated client can never meet one it has no branch for.

The shape of the bill: calls are what a bad access pattern inflates by two orders of magnitude; downloads track the content you actually take and barely move. Batching and exporting do not buy cheaper content — they buy back the 99% of requests that were never about content at all.

Every operation also carries an x-scolavo-cost extension — typical response bytes and the meters it moves — so a generated client can surface the price at the call site. And because the document’s ETag tracks contentVersion, this is also the cheapest gate in the API:

# The entire incremental sync, most of the time — and it needs no token at all:
curl -s -o /dev/null -w '%{http_code}\n' \
  "https://mcp.scolavo.com/v1/openapi.json" \
  -H 'If-None-Match: "<the etag you stored last time>"'
# 304  →  the corpus has not moved. Stop.

Zero body bytes on that 304, no database reads, and no calls unit. The X-Scolavo-Content-Version header on the same 304 tells you which build you are being told about, so you can log it without parsing anything.