Skip to Content

Amal Developer Documentation

Amal is the Arabic-literacy decision system for teachers in the Arab world. This portal documents its HTTP API: a REST + JSON interface, fully described by an OpenAPI 3.1 specification.

It documents two layers. The provisioning surface (authentication, tenancy for organizations, schools, and classes, and user management) is covered in Getting Started and the Guides. The measurement-led RTI engine (the diagnostic loop, skill-status decisions, student profiles, intervention bundles, progress monitoring, and reporting) is now shipped and documented in How Phase 1 Works and the per-subsystem guides.

New to the platform? Read How Phase 1 Works → The RTI Loop for the end-to-end story before drilling into any single subsystem.

Base URL and versioning

The API is served under /api. The current specification is version: 1.0.0-phase0. Wave 1 is a single, un-versioned documentation site; a /v1/… path is reserved for a future versioned API.

Throughout these docs the base URL is written as https://localhost:3000; replace it with the address of your running apps/server.

How the API is grouped

Operations are grouped by tag; the API Reference renders them that way. The provisioning tags:

  • auth: register, login, refresh, me, logout, password reset, student quickCode. See Authentication.
  • tenancy: organizations, schools, classes, organization rollup. See Core Concepts.
  • users: provisioning, persona profiles, rosters, principals, managers, parent links. See Provision Users.
  • system: health check.

The RTI-engine tags (diagnostic-session, practice, engine, sub-skills, sse, profile, bundle, cluster, workflow, monitoring, orf / cbm, standards, delivery, reporting, parent-pdf, warmup, language-safety, qa, and logging) each have a conceptual guide under Guides. Start with How Phase 1 Works to see how they connect.

Authentication in one sentence

Every request after login carries a Bearer JWT: Authorization: Bearer <accessToken>. See Authentication for the full model.

Conventions

  • Bodies and responses are JSON.
  • Every error uses one envelope: { code, message, details?, retryAfter? }. See Errors.
  • Two ID types, by design. Tenancy resources (Organization, School, Class) use cuid string IDs matching ^c[a-z0-9]{24}$. Users and persona profiles use integer IDs. Do not assume one ID type across the whole API: a class ID is a cuid string, a user ID is an integer.

Where to start

New here? Go straight to Getting Started. It walks from provisioning the bootstrap admin to your first authenticated call, with copy-paste examples that work against a running server.

Last updated on
Getting Started