Classroom API specification notes
Reference scope
https://handwrites.io. This edition contains the 30 documented /api/v1/orgs operations used with class organisations. They are shared routes, so list results and shared enums may also describe teams. Send kind: "class" when creating an ordinary class and validate the selected organisation's kind in your application./api/v1/openapi.json. This edition is a curated subset, not another server version. Document CRUD, content, files, audio, settings, OAuth and personal identity are covered in Regular Accounts. Live collaboration has a separate socket contract.Authentication and authorisation
Authorization: Bearer <credential> on every operation in this edition. JSON request bodies need Content-Type: application/json. The public wrapper does not read app cookies and does not provide authenticated cross-origin browser CORS; keep integration credentials on a backend.orgs:manage does not let a co-teacher rename a class or turn a student into a teacher./api/v1 credentials. Managed student keys can carry supported scopes but cannot request orgs:manage; their identity remains the student. Current-source organisation admin tokens may carry orgs:manage, but remain the class principal, not a human owner. OAuth is allowed only when effective API and third-party policy permit it.Errors, retries and one-time secrets
{"error":{"code":"…","message":"…"}}. Keep Request-Id for diagnostics without logging the credential or returned secret.| Status | Expected client behavior |
|---|---|
| 400 | Correct schema, role, parameter or content type. Class roles are limited even when the shared enum lists team roles. |
| 401 | Obtain a valid credential; stop retrying a revoked/expired token. |
| 402 | Seat capacity or plan feature may be required; show the appropriate administrator action. |
| 403 | Scope, role, owner, policy, school protection or credential-kind restriction; do not try alternate endpoints to bypass it. Some managed-token plan failures also use 403. |
| 404 | Missing or inaccessible organisation/member/token/invitation; do not infer another school's existence. |
| 409 | Existing membership or request conflict; reconcile current state. Honor Retry-After for idempotency-in-progress. |
| 422 | Limit reached or idempotency mismatch; repair the request. |
| 429 | Respect Retry-After and back off; observe returned usage limits. |
| 5xx | Preserve user intent. Retry only when the operation is safe or has supported idempotency. |
Idempotency-Key here are ordinary organisation creation, direct member addition and invitation creation. Use a new UUID for a logical action and reuse it only for the identical retry with the same credential, method, URL and body. Stored successful JSON responses last 24 hours; mismatched reuse is rejected. Do not assume all writes support it.dailyRequests policy value is not currently used by that public request counter. Monthly audio policy is a separate control. Use Handwrite-Requests-Limit, Handwrite-Requests-Remaining and returned retry information instead of treating these defaults as a guaranteed allocation.Lists and usage
GET /orgs and the membership/invitation lists return their documented collections; do not invent cursor parameters for them. Class capacity is capped at 5,000 members and a person at 100 organisations, with plan seats applying below those ceilings. Pending invitations also consume relevant seat capacity.limit, cursor and since. Follow opaque cursors until null. Normal lists omit deleted records; incremental lists include tombstones while retained, and are oldest-first. Advance a sync checkpoint only after processing every page. The document API's retention and revision rules are in the Regular Accounts specification.Schema and deployment boundaries
rules is a complete replacement object; it is not merge-patch. Always combine schema validation with the operation README and server response.Modified at 2026-10-26 13:24:24