---
title: "Overview"
url: https://docs.growamal.com/en/
language: en
---

# 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](https://docs.growamal.com/en/getting-started/) and the
[Guides](https://docs.growamal.com/en/guides/provision-users/). 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](https://docs.growamal.com/en/how-it-works/) and the per-subsystem guides.

New to the platform? Read **[How Phase 1 Works → The RTI Loop](https://docs.growamal.com/en/how-it-works/)** 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 `http://localhost:8787` (default port 8787;
configure via the `PORT` env var); replace it with the address of your running `apps/server`. The
Next.js frontend dev server runs on port 3000 -- do not confuse the two.

## How the API is grouped

Operations are grouped by tag; the [API Reference](https://docs.growamal.com/en/api-reference/) renders them that way. The
provisioning tags:

- **`auth`**: register, login, refresh, `me`, logout, password reset, student quickCode.
  See [Authentication](https://docs.growamal.com/en/authentication/).
- **`tenancy`**: organizations, schools, classes, organization rollup.
  See [Core Concepts](https://docs.growamal.com/en/core-concepts/).
- **`users`**: provisioning, persona profiles, rosters, principals, managers, parent links.
  See [Provision Users](https://docs.growamal.com/en/guides/provision-users/).
- **`system`**: health check.

The RTI-engine and supporting tags (`diagnostic-session`, `practice`, `engine`, `sub-skills`,
`sse`, `profile`, `bundle`, `cluster`, `workflow`, `monitoring`, `orf`, `cbm`, `standards`,
`delivery`, `reporting`, `parent-pdf`, `warmup`, `language-safety`, `qa`, `logging`,
`gamification`, `leaderboard`, `notifications`, `lms`, `session-catalog`, `sync`, `fidelity`,
`rti`, `data-room`, `decision-packet`, `audit`, `blob`, `paper-results`, `onboarding`,
`student-flow`, `parent-portal`, and more) are all rendered in the API Reference.
Start with [How Phase 1 Works](https://docs.growamal.com/en/how-it-works/) to see how they connect.

## Authentication in one sentence

Every request after login carries a **Bearer JWT**: `Authorization: Bearer <accessToken>`. See
[Authentication](https://docs.growamal.com/en/authentication/) for the full model.

## Conventions

- **Bodies and responses are JSON.**
- **Every error** uses one envelope: `{ code, message, details?, retryAfter? }`. See [Errors](https://docs.growamal.com/en/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](https://docs.growamal.com/en/getting-started/)**. It walks from provisioning the
bootstrap admin to your first authenticated call, with copy-paste examples that work against a
running server.