Read Learning Plans through the API

The initial Learning Plans API is read-only. It requires learning_plans:read, effective API read access, and Learning Plans enabled for the authenticated school.

• GET /learning-plans lists plans and accepts status and student_id filters plus snapshot synchronization parameters.
• GET /learning-plans/{id} returns one plan.
• GET /learning-plans/{id}/assignments returns its assignment and supersession history and can filter by assignment status.

There are no API v1 operations to create, activate, pause, edit, generate, approve, publish, postpone, replace, or cancel Learning Plans. Use the authenticated school application for those human-controlled actions.

A plan includes:

• student and optional semester identifiers;
• name, period start, and target completion date;
• ascending or descending direction;
• canonical start and destination positions;
• plan state;
• versioned Quran workload dataset identifier;
• currently effective publication policy, automation pause, and policy source;
• workload tracks with type, unit, target, tolerance, next position, and completion time.

The effective policy can change when school, halqa, or learner configuration changes. Treat it as current response state, not immutable creation metadata.

Assignments include due date, lifecycle state, source, safe explanation, publication/start/completion/supersession times, a replacement link when applicable, and ordered canonical Quran segments.

Private staff notes are never returned. The school-server API can include draft and other staff lifecycle states because it is not the parent portal; protect the response accordingly.

1. List plans using the desired status or student filter.
2. Traverse the complete filter-bound snapshot.
3. Upsert plan state by id.
4. For relevant plans, traverse assignment history and preserve supersession links rather than deleting old items.
5. Use updated_after in later complete cycles.
6. Do not combine records across schools or expose staff states to parents.

An unavailable feature can return a feature-specific denial even when the key contains the scope. Existing keys do not acquire learning_plans:read automatically; rotate to a deliberately scoped key.

See pagination and synchronization and the public Learning Plans concepts.