Read Learning Plans through the API

The initial Learning Plans API is read-only. It requires learning_plans:read and effective API read access for the authenticated school. If the school later disables Learning Plans, authorized historical reads remain available as described below.

• 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;
• nullable immutable creation_provenance for quantity-created plans.

Quantity provenance contains non-sensitive creation mode, requested and actual quantity/unit, direction, calculation status, progress basis, source endpoint and rating category, dataset and calculation versions, origin/direction/quantity override facts, and repeat and bulk-operation correlation. It deliberately omits the source recitation ID. The field is null for fixed-range, manual, and historical plans without a provenance row. Do not infer or fabricate it.

Treat dataset source versions in API provenance as opaque reproduction values, not display copy. Human interfaces should use Waqar’s localized dataset name or edition and must not try to parse the technical source value.

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.

When Learning Plans is disabled, all three operations preserve historical read compatibility and return X-Waqar-Feature-Mode: historical-read-only. The header means no new planning work can be created or changed; it does not bypass tenant, API rollout, key, scope, suspension, or quota checks. Keep synchronizing the retained records and do not delete them locally just because this header appears.

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.