Platform API v1

Base path: /platform/v1. Every route requires a machine token and the scope listed beside it. Bodies are strict JSON: an unknown field is rejected.

Every route is a thin adapter over the same services MTP’s own portal uses. The learner is named explicitly on every call that concerns one; the machine credential is never treated as a person.

Courses are the only thing the Platform API launches. A metahuman conversation, a quiz, a justification, and an assessment are steps inside a course; you enroll a learner in the course and hand them a sign-in ticket to it, and MTP runs the steps.

Content

GET /content-items — content.read

Published content items in the organization, newest first. Query parameters: type (a content-type key such as course) and tag.

Returns an array of item summaries: id, type key, title, status, tags, current version number, timestamps. The document itself is not exposed here.

GET /content-items/{itemId} — content.read

One published item summary. 404 when the item is unpublished or not in the organization.

Learners

Learners are MTP users who are members of your organization. The Platform API never creates users; provisioning stays with invitations, SCIM, SSO, or LTI.

GET /learners?email= — learners.read

Members whose email matches exactly (case-insensitive). Returns up to five, usually one.

[{ "id": "…", "email": "learner@example.org", "displayName": "A. Learner", "status": "ACTIVE" }]

GET /learners/{learnerId} — learners.read

One member. 404 for anyone who is not a member of the organization.

Enrollments

POST /enrollments — enrollments.write

Enroll a learner in a published course.

{ "learnerId": "…", "courseItemId": "…" }

Idempotent: a learner already actively enrolled gets their existing enrollment back. Returns the enrollment (201) — its id, the pinned course version, status, and progress. 404 when the learner is not a member; 409 when the course has no published version.

To put the learner in front of it, open the portal for them with a sign-in ticket whose destination is course.

GET /enrollments/{enrollmentId} — enrollments.read

One enrollment with progress: status, the share of required steps completed, and each step’s status, attempts, and score.

GET /learners/{learnerId}/enrollments — enrollments.read

Every enrollment of one learner, as above.

Sign-in tickets

POST /sign-in-tickets — learners.sign_in

See Sign-in tickets.

Errors