REST API

A plain HTTP API over your course data — courses, modules, lessons, students, settings and translations. If you or your developer want to build something the app does not do (a sync script, an internal dashboard, your own agent), this is the door.

It uses the same key as an AI assistant does. There is no second credential to create: the key from Settings > Developers is the key you send here, and the permissions you ticked on it decide which endpoints answer.

Base URL and header

https://luna-online-course.firebaseapp.com/rest_api/v2

Every request carries the key as a bearer token, and every request with a body is JSON:

Authorization: Bearer mcp_your-key-here
Content-Type: application/json

The key is a secret in a request header, so it belongs on a server, never in a browser or a mobile app you ship. Anyone holding it has exactly the permissions you ticked.

An OAuth access token works here too, and is treated exactly the same way — it carries the same permissions, and everything on this page applies to it unchanged.

Your first call

GET /whoami works with any valid key and needs no permission at all, which makes it the fastest way to prove your setup works:

curl -s https://luna-online-course.firebaseapp.com/rest_api/v2/whoami \
  -H "Authorization: Bearer $COURSE_KEY"

{
  "success": true,
  "data": {
    "apiVersion": "2.0.0",
    "shopId": "shop_123",
    "shopDomain": "example.myshopify.com",
    "keyId": "k_456",
    "keyName": "Reporting script",
    "read": ["dashboard", "course", "student", "setting"],
    "actions": ["course.create", "course.edit"],
    "expiresAt": "2026-11-18T00:00:00.000Z",
    "active": true,
    "fieldGroups": {"course": {"course.edit": ["title", "description"]}},
    "fieldTypes": {"student": {"email": "string", "courseIds": "string[]"}}
  }
}

Why /whoami matters

It is the discovery call. Instead of hardcoding what your integration may do, ask:

• read and actions — the permissions this key holds. Check them before offering a feature, and you can tell a user "this key can't do that" instead of showing them a 403.
• fieldGroups — which fields each permission may write, per resource, served straight from the server's own lists. Build your forms and validation from this and they cannot drift out of step with the API.
• fieldTypes — the declared type of those fields (string, boolean, string[]). Advisory: it tells your client what to build, but the server's own value guards are what enforce it. A resource missing from the map carries no type constraint at all.
• expiresAt and active — when the key runs out, and whether it is still usable. expiresAt is null for a key created with no expiration, and for an OAuth session, whose lifetime is the token's own.
• apiVersion — read it rather than hardcoding a version.

The envelope

Every answer has the same shape, success or failure.

Success

{"success": true, "data": {"id": "c1", "title": "Intro to Ceramics"}}

Success on a list — lists, and only lists, also carry meta:

{
  "success": true,
  "data": [{"id": "c1"}],
  "meta": {"count": 1, "total": 250, "pagination": {"hasNext": true}}
}

count is how many rows came back, total how many matched (only where the service counted them), pagination carries hasNext, hasPre, totalPage and sometimes note.

Failure

{
  "success": false,
  "error": "Course still has students",
  "code": "COURSE_HAS_STUDENTS",
  "details": {"studentCount": 3}
}

The 27 endpoints

Permission is the scope the key must hold. Read scopes are plain words (course, student, setting, dashboard); action scopes always contain a dot, and that dot is the whole difference — holding course does not open course.edit.

A call the key has no permission for answers 403 SCOPE_DENIED, naming the scope it needed.

Identity

Dashboard

Courses

Modules

Lessons

Students

Settings

Translations

Notification emails

Part of Settings, so both take setting.edit_notifications.

Reading data

curl -s "https://luna-online-course.firebaseapp.com/rest_api/v2/courses?limit=5&status=published" \
  -H "Authorization: Bearer $COURSE_KEY"

Two things to know before you branch on a response:

• Only three reads answer 404 when a record is missing: GET /courses/:id, GET /lessons/:lessonId and GET /students/:id. Nowhere else does a 404 mean "bad id".
• A list with a wrong parent id answers 200 with an empty array. GET /courses/unknown-id/modules means "no modules", not "no course". Likewise GET /translations?code=xx-YY answers 200 for a locale that does not exist, with found: false in the payload — that flag is the only signal a wrong code gives.

Writing data

curl -s -X POST https://luna-online-course.firebaseapp.com/rest_api/v2/courses \
  -H "Authorization: Bearer $COURSE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Intro to Ceramics", "status": "draft"}'

Rules that are easy to trip over:

• Settings are flat dot-paths, one per writable path — the server rebuilds the nested object: {"appearance.primaryColor": "#1a73e8", "email.enrollmentEmail": false}. The writable paths are general.appDisplayName; appearance.portalLogoUrl, appearance.primaryColor, appearance.myCoursesPageTitle, appearance.startLearningButton, appearance.continueButton, appearance.completedBadge; email.senderName, email.replyToEmail, email.enrollmentEmail, email.completionEmail.
• Reordering is a POST on a sub-resource, and every DELETE takes its id from the path — a body on a DELETE is not read.
• courseIds must be an array, even for a single course. "courseIds": "c1" is a 400 INVALID_INPUT.
• A required field left out is a 400 INVALID_INPUT, and a blank string counts as left out. POST /students needs email; POST /notifications/test-email needs templateKey. A templateKey that is well-formed but does not exist is a 404 NOT_FOUND, with no mail sent.
• thumbnailUrl must be an https URL. There is no file upload over this API.
• POST /courses never accepts certificate, whatever the key holds — it always comes back ignored. Set it afterwards with PUT /courses/:id, which is where course.manage_certificate applies.
• POST /notifications/test-email takes no recipient. It goes to the shop's own contact address; any recipient you send is reported as ignored.
• Adding or removing a locale is not available over the API. PUT /translations patches the locales you send and leaves the rest alone.

ignoredFields is not an error

Send a field the key may not write — or one the endpoint does not accept — and the request still succeeds. The field is dropped and named back to you:

{
  "success": true,
  "data": {
    "updated": true,
    "data": {"id": "c1"},
    "ignoredFields": ["certificate"],
    "note": "Fields outside this permission were ignored."
  }
}

When every field you sent was out of scope, nothing is written and updated is false, with a note saying so.

Pagination

This is the part integrations most often get wrong. There are three different behaviours, and which one you get depends on the endpoint.

Normal lists: page with after

GET /courses and GET /students are the two cursor-paged lists.

• limit — how many rows, capped at 100, default 20 on these two lists. A value that isn't a whole number is ignored rather than guessed at: ?limit=10abc does not become 10.
• after — the id of the last row of the page you just read. Leave it out for page one.

Read meta.pagination.hasNext. While it is true, take the id of the last row and send it as ?after= on the next call:

curl -s "https://luna-online-course.firebaseapp.com/rest_api/v2/students?limit=100&after=stu_9f2" \
  -H "Authorization: Bearer $COURSE_KEY"

There is no before: paging backwards is not offered.

Search cannot be paged

Search is ranked on a different backend from the cursor, so honouring both would hand you page one forever. Instead, a search returns the best matches it can fit in one page:

• meta.total — how many rows actually matched;
• meta.count — how many came back;
• meta.pagination.hasNext — always false on a search;
• meta.pagination.note — present when rows were left behind, with the server's own sentence explaining it.

So when total is larger than count, do not retry with after. Either narrow searchText, or raise limit (max 100). If your client shows its own pagination advice, let note win over it.

If the search backend itself is down you get 503 SEARCH_UNAVAILABLE — never an empty list, so "no results" always means no results.

Two lists are not paged at all

GET /courses/:courseId/modules and GET /courses/:courseId/lessons behave differently from everything above:

• Send no limit and you get every row — not 20, not 100. The cap of 100 only applies to a limit you actually sent (?limit=500 becomes 100).
• Neither ever carries meta.pagination. There is no hasNext to read, only meta.count.
• /lessons takes no offset — only limit. It can be truncated, not paged, and nothing tells you how much was left behind. Ask for everything, or accept the cut.
• /modules takes offset (capped at 1000) and that is the only way forward. Since there is no hasNext, page until a call returns fewer rows than the limit you asked for.

visibility is not a filter

?visibility=private on GET /courses is not applied — it used to be advertised while nothing applied it, so it was removed rather than left to mislead. visibility is still on every row that comes back: filter on your side.

Rate limiting

60 requests per minute per key. Over the limit you get 429 RATE_LIMITED with a Retry-After header in seconds.

Read the number in that header and wait it out — don't invent your own backoff. The header has been on every 429 since 2.0.0 and will stay.

This is a runaway-client guard, not a billing control. Authentication failures are counted per IP as well, so a script hammering with a bad key is throttled before it reaches a route.

Error codes

Branch on code. This is all of them.

An unknown path answers a JSON body too, never an empty 404 — so you can always tell "wrong URL" from "wrong key".

Related

• MCP Keys — create the key, choose its permissions, regenerate or revoke it.
• What each permission unlocks — what each permission on that key actually allows.
• MCP Desktop Setup — same key, for assistants that run a local server instead of calling this API themselves.