Start here — Classroom for developers
Handwrite Classroom for outside developers#
Build an integration around a selected class and the permission of the person or organisation that connected it. Handwrite represents a class as an organisation with kind: "class" and principal class:<orgId>. A class can own documents, have teachers and students, and apply policies to their app use.An ordinary class and a staff-provisioned school are different. POST /api/v1/orgs can create an ordinary class; it does not create school login accounts or a school code. A school applies through Handwrite support, then its authorised staff use the school workflow. See School and student workflows.Start here#
2.
Authenticate on your backend and call GET /api/v1/me to check who the token represents.
3.
Call GET /api/v1/orgs with orgs:read, filter the response to kind: "class", and ask the person to select the class. There is no documented kind query filter.
4.
Read the selected organisation, relevant policy and documents. Only display controls that the caller may use; the API still enforces each operation.
curl --fail-with-body https://handwrites.io/api/v1/me \
-H "Authorization: Bearer $HANDWRITE_API_TOKEN"
curl --fail-with-body https://handwrites.io/api/v1/orgs \
-H "Authorization: Bearer $HANDWRITE_API_TOKEN"
curl --fail-with-body https://handwrites.io/api/v1/orgs/REPLACE_ORG_ID/documents \
-H "Authorization: Bearer $HANDWRITE_API_TOKEN"
Design the integration around explicit choices#
Connecting an account, selecting a class and selecting documents are separate decisions. Do not silently import every student document. Class-owned documents come from the organisation document list; that list is not a directory of all students' personal documents. A fine-grained key may expose only selected documents, and access can change later.Show who is acting: the teacher, an approved managed student identity, or the organisation itself. Keep class names and student details out of diagnostics. Use Request-Id when reporting failures. Clear class-specific cached data when access ends and keep unsaved local edits until the server confirms a save.A classroom app should explain what usage administrators can see. Counters and collaboration summaries are not learning assessments. Follow the policy and data-use notes when presenting activity, exporting CSV or requesting speech processing.Documentation map#
Each HTTP reference has a separate README with application use, required standing, an example, parameters and responses. The shared organisation schema may mention team roles; valid classroom roles remain teacher, co-teacher, billing and student.Verification boundary#
The public OpenAPI source matched the deployed full specification on 2026-10-26. The additional notes were checked against the working tree. Some developer-access controls are in-progress working-tree features, and provider checks found no Team or Classroom portal DNS/CloudFront alias at that snapshot. Source code and these docs do not prove those portals or student sign-in are deployed. No real student account, roster upload, authenticated classroom write or live room was exercised for this documentation task.Modified at 2026-10-26 13:24:24
