1. Class setup
Handwrite Classroom
  • Handwrite Classroom
    • Start here — Classroom for developers
    • Classroom API specification notes
    • Classroom socket specification notes
    • Classroom live socket — README
    • Classroom identities, credentials and roles
    • School and student workflows
    • Classroom policy and data-use notes
    • Class setup
      • README — GET /api/v1/orgs
      • README — POST /api/v1/orgs
      • README — GET /api/v1/orgs/{id}
      • README — PATCH /api/v1/orgs/{id}
      • README — DELETE /api/v1/orgs/{id}
      • Class setup API — README
      • Choose a class from the returned organisations
        GET
      • Create an ordinary class
        POST
      • Read the selected class
        GET
      • Rename a class
        PATCH
      • Delete an ordinary class
        DELETE
    • Invitations
      • README — GET /api/v1/orgs/invitations
      • README — POST /api/v1/orgs/invitations/{inviteId}/accept
      • README — POST /api/v1/orgs/invitations/{inviteId}/decline
      • README — GET /api/v1/orgs/{id}/invitations
      • README — POST /api/v1/orgs/{id}/invitations
      • README — DELETE /api/v1/orgs/{id}/invitations/{inviteId}
      • Invitations API — README
      • Read invitations to the signed-in person
      • Accept a class invitation
      • Decline a class invitation
      • List pending class invitations
      • Invite a person by email
      • Cancel a pending invitation
    • People
      • README — GET /api/v1/orgs/{id}/members
      • README — POST /api/v1/orgs/{id}/members
      • README — PATCH /api/v1/orgs/{id}/members/{principal}
      • README — DELETE /api/v1/orgs/{id}/members/{principal}
      • README — POST /api/v1/orgs/{id}/leave
      • People API — README
      • Read the visible membership roster
      • Add an existing person to a class
      • Change a class member role
      • Remove an ordinary class membership
      • Leave an ordinary class
    • Documents
      • README — GET /api/v1/orgs/{id}/documents
      • Documents API — README
      • List class-owned documents
    • Plan and usage
      • README — GET /api/v1/orgs/{id}/billing
      • README — GET /api/v1/orgs/{id}/usage
      • README — GET /api/v1/orgs/{id}/usage/live
      • README — GET /api/v1/orgs/{id}/members/{principal}/usage
      • README — GET /api/v1/orgs/{id}/insights
      • Plan and usage API — README
      • Read classroom plan and seat information
      • Read classroom usage totals
      • Read the recent classroom activity window
      • Read one member usage
      • Read classroom collaboration insights
    • Policies
      • README — GET /api/v1/orgs/{id}/policies
      • README — PUT /api/v1/orgs/{id}/policies
      • README — GET /api/v1/orgs/{id}/members/{principal}/policy
      • README — PUT /api/v1/orgs/{id}/members/{principal}/policy
      • README — DELETE /api/v1/orgs/{id}/members/{principal}/policy
      • Policies API — README
      • Read class-wide policy
      • Replace class-wide policy rules
      • Read one member policy
      • Replace one member policy override
      • Clear one member override
    • Managed tokens
      • README — GET /api/v1/orgs/{id}/members/{principal}/tokens
      • README — POST /api/v1/orgs/{id}/members/{principal}/tokens
      • README — DELETE /api/v1/orgs/{id}/members/{principal}/tokens/{tokenId}
      • Managed tokens API — README
      • List tokens issued to a member
      • Issue a managed student token
      • Revoke a managed token
  1. Class setup

Create an ordinary class

POST
/api/v1/orgs
Classroom integration: Use kind: "class". The human creator becomes the owning teacher. This does not provision a school, generate a school code, create student-pool accounts or arrange school approval. Staff-provisioned schools start through the school application workflow. Organisation tokens cannot create organisations.
Required standing: A user principal with orgs:manage; not an organisation-owned token.

Request

Authorization
Bearer Token
Provide your bearer token in the
Authorization
header when making requests to protected resources.
Example:
Authorization: Bearer ********************
or
OAuth 2.0
Authorization Code
Add the parameter
Authorization
to Headers，whose value is to concatenate the Token after the Bearer.
Example:
Authorization: Bearer ********************
Authorize URL: https://handwrites.io/oauth/authorize
Token URL: https://handwrites.io/api/oauth/token
Refresh URL: https://handwrites.io/api/oauth/token
Scopes:
orgs:manage-Create, rename and delete teams and classrooms, manage members and invitations, join and leave
or
Header Params

Body Params application/jsonRequired

Examples

Responses

🟢201
application/json
You are its owner (team) or teacher (class).
Headers

Bodyapplication/json

🟠400BadRequest
🟠401Unauthorized
🟠403Forbidden
🟠409Conflict
🟠422Unprocessable
🟠429TooManyRequests
🔴500ServerError
Request Request Example
Shell
JavaScript
Java
Swift
curl --location '/api/v1/orgs' \
--header 'Idempotency-Key;' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "kind": "team",
    "name": "string"
}'
Response Response Example
201 - Example 1
{
    "id": "string",
    "kind": "team",
    "principal": "user:3f2b…",
    "name": "string",
    "owner": "user:3f2b…",
    "role": "owner",
    "createdAt": "2019-08-24T14:15:22.123Z",
    "updatedAt": "2019-08-24T14:15:22.123Z"
}
Modified at 2026-10-26 13:12:44
Previous
Choose a class from the returned organisations
Next
Read the selected class
Built with