PARTNERS

API

Last updated: 23 September 2026

Public partner reference for Learn with Odi: Metodbox sign-in, shared identity, completion events, Jupas, and school report mail. Application routes under /api/ are not listed here.

OVERVIEW

What this page covers

A public contract for school portals and Macenta products that connect to Learn with Odi. It describes identity, sign-in, shared progress, and school report mail — not private application endpoints.

Product code: learn-with-odi
Audience: School LMS partners, Macenta product teams, and schools adding Learn with Odi without custom product code.
Status: Living reference. Existing school links keep working while the shared Macenta services roll out.

IDENTITY

Who a user is

Learn with Odi maps a school person to one platform account. The school mailbox is stored when provided; sign-in uses the platform address.

username: Stable school username (no domain).
loginHint: Platform sign-in address: {username}@learnwithodi.com.
orgEmail: Optional real school mailbox. Not used to sign in.
displayName: Given name and family name.
role: student, teacher, or schooladmin.
orgId / orgName: School or organisation.
campusId / campusName: Campus within the school.
classes[]: Class name, grade (typically 1–4), and content level.
locale: Preferred interface language, for example en or tr.
entitlements[]: Macenta products this person may open.

Roles in Learn with Odi
Role	After sign-in
student	Learner home and weekly lessons
teacher	Class tools, reports, and Friday uploads
schooladmin	School-wide administration and reports

SIGN-IN

How a school sends a learner

Metodbox redirects the browser to Learn with Odi with a short-lived signed session token in ?token=. Learn with Odi creates or resumes the matching account. Entitled Macenta products open without signing in again.

Entry URL: https://www.learnwithodi.com/login?token=<signed-token>

The same token is accepted on the site origin with ?token=. The payload should identify the person (username, name, role) and their organisation (school, campus, classes). Teachers may belong to more than one class. School portal tokens typically send student or teacher; schooladmin is a provisioned school-staff role.

POST /v1/auth/exchange — request

{
  "grantType": "lms_token",
  "product": "learn-with-odi",
  "lmsToken": "<signed Metodbox session token>"
}

POST /v1/auth/exchange — response

{
  "macentaUserId": "usr_example",
  "launchToken": "<short-lived token>",
  "user": {
    "username": "student123",
    "loginHint": "student123@learnwithodi.com",
    "orgEmail": "student123@example-school.edu",
    "displayName": "Ada Example",
    "role": "student",
    "orgId": "example-school",
    "orgName": "Example School",
    "campusName": "Main Campus",
    "classes": [{ "name": "3A", "grade": 3, "level": "3" }],
    "locale": "en",
    "entitlements": ["learn-with-odi"]
  }
}

COMPLETIONS

Progress that can be shared

Authorised products may read portable activity. Learn with Odi does not publish upload files or Jupa wallets through this contract.

activity.completed: A weekly lesson or unit section is finished (listening, reading, or similar).
quiz.completed: A checkpoint or Friday quiz attempt is submitted, with score and time spent.
speaking.completed: A speaking practice session is finished, with score and duration.
assignment.submitted: A Friday upload or open task is handed in. File bodies are not shared by default.
session.seen: The learner was last active.

Portable data fields

unitId: Lesson, theme, or course title.
sectionId: Section within the lesson.
progressPercent: Completed sections divided by total sections.
score / maxScore: Normalised lesson or quiz score, typically 0–100.
durationSec: Speaking session length.
timeSpentSec: Quiz time on task.
streakDays: Consecutive active days.
lastSeenAt: Most recent activity timestamp (ISO 8601).

POST /v1/events

{
  "product": "learn-with-odi",
  "macentaUserId": "usr_example",
  "type": "activity.completed",
  "occurredAt": "2026-09-23T10:00:00Z",
  "orgId": "example-school",
  "className": "3A",
  "data": {
    "unitId": "Life Skills Week 4",
    "sectionId": "Listening",
    "progressPercent": 25,
    "score": 72,
    "maxScore": 100
  }
}

Stays inside Learn with Odi

Jupa wallet balances and in-product leaderboards
Weekly lesson catalogues and media packages
Friday upload files, writing bodies, and teacher comments
Checkpoint question banks and answer keys
Newcomer onboarding and publisher tools

JUPAS

Points in Learn with Odi

Jupas are the in-product currency learners earn from lessons, checkpoints, speaking, and teacher marks.

Partners can consume portable scores and completion percentages. They do not create, spend, or correct Jupa balances. A lesson score on a completion event is a 0–100 result, not a wallet mutation.

School report mail

Learn with Odi sends branded weekly and monthly school reports to a short list of named administrators — not to every teacher by default.

Mail is sent as Learn with Odi from noreply@learnwithodi.com. The product still decides who receives a report and builds the HTML. A shared Macenta mail service only delivers the message.

POST /v1/mail/send

{
  "product": "learn-with-odi",
  "from": { "email": "noreply@learnwithodi.com", "name": "Learn with Odi" },
  "replyTo": "destek@macenta.com.tr",
  "to": ["head@example-school.edu"],
  "subject": "Learn with Odi | Example School weekly report ready",
  "html": "<!DOCTYPE html>…",
  "tags": {
    "type": "weekly_school_report",
    "weekKey": "2026-W38",
    "school": "Example School"
  }
}

HTTP

Partner reference

Draft Macenta partner paths. They are not this website’s /api/ application routes. Errors return a short code; products map that to a safe message.

Partner HTTP methods and paths
Method	Path	Purpose
POST	/v1/auth/exchange	Exchange a school or product session for a short-lived launch token and profile.
GET	/v1/me	Return the signed-in profile.
GET	/v1/users/{id}	Read a user in the same organisation, when authorised.
POST	/v1/launch	Open another entitled Macenta product without signing in again.
GET	/v1/products	List products this organisation may use.
PUT	/v1/orgs/{orgId}	Register or update a school once. No product-side custom code for a standard school.
POST	/v1/mail/send	Send transactional HTML mail as Learn with Odi.
POST	/v1/events	Publish a portable completion or activity event.
GET	/v1/users/{id}/activity	Read portable activity for an authorised viewer.

POST /v1/launch

{
  "from": "learn-with-odi",
  "to": "speakr",
  "macentaUserId": "usr_example",
  "returnUrl": "https://www.learnwithodi.com/home",
  "locale": "en",
  "context": {
    "assignmentId": "week-4-speaking",
    "completion": {
      "unitId": "Life Skills Week 4",
      "sectionId": "Speaking"
    }
  }
}

PUT /v1/orgs/{orgId}

{
  "displayName": "Example School",
  "products": ["learn-with-odi"],
  "campuses": [{ "id": "main", "name": "Main Campus" }]
}

Error body

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "This request is not allowed."
  }
}

SCHOOLS

Adding a school

Register the organisation once — name, campuses, and entitled products. Learners then arrive from Metodbox or from a provisioned roster.

A standard school does not need custom work inside Learn with Odi. For access or a test organisation, write to destek@macenta.com.tr.