1. Teams
Handwrite Team
  • Handwrite Team
    • Teams
      • 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}
      • Your teams and classes
        GET
      • Create a team or class
        POST
      • One of your organisations
        GET
      • Rename a team (owner or admin)
        PATCH
      • Delete with its memberships, invitations, documents and shares (owner)
        DELETE
    • Membership
      • 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}/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
      • README — GET /api/v1/orgs/{id}/invitations
      • README — POST /api/v1/orgs/{id}/invitations
      • README — DELETE /api/v1/orgs/{id}/invitations/{inviteId}
      • Organisation invitations to your verified email
      • Join with the invited role
      • Decline an organisation invitation
      • Members (students see teachers and themselves)
      • Add a person (managers)
      • Change a role; owner transfers a team
      • Remove a member (managers) or yourself
      • Leave (not the owner)
      • Pending email invitations (managers)
      • Invite an email (managers)
      • Withdraw an invitation (managers)
    • Documents
      • README — GET /api/v1/orgs/{id}/documents
      • Documents the organisation owns
    • Billing 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, status and seats per role (billing.read)
      • Usage per day and member (admins, managers, billing)
      • The last 60 minutes per member (admins, managers, billing)
      • One member's usage (usage.read, or yourself)
      • How people collaborate on the org's documents
    • 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
      • Org-wide policy rules (policies.read)
      • Replace the org-wide rules (admins)
      • A member's override and what applies to them
      • Replace a member's override (admins; managers for members)
      • Remove a member's 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 issued to a member (tokens.read)
      • Issue a managed fine-grained token (admins, billing)
      • Revoke a managed token (admins, billing)
    • Guides
      • Start here — Team app integration
      • Team API specification notes
      • Team socket specification notes
      • Team live socket — README
      • Team roles and access model
      • Team credentials and developer setup
      • Team SSO and portal workflows
      • Team policies, plans and seats
      • Team usage and collaboration insights
      • Team webhook delivery — README
  1. Teams

README — GET /api/v1/orgs

Your teams and classes#

GET /api/v1/orgs · Operation ID: listOrgs

App purpose#

Filter returned organisations by kind === "team". The shared route can return classes too. Keep the selected team explicit; a user can belong to multiple organisations. An org-owned credential is limited to its own principal.

Authentication and authority#

Bearer credential with orgs:read. Any authenticated caller with this scope; results reflect current membership.
Scopes do not replace role, ownership, plan, current membership or effective-policy checks. The team edition uses the shared organisation route with a team ID; it does not change the backend schema for classes.

Example#

Replace all REPLACE_* values and use an authorised disposable team for tests. Read-only examples still require the appropriate data access. Mutating examples change team state; policy PUT examples are complete replacements.
curl --fail-with-body -X GET 'https://handwrites.io/api/v1/orgs' \
  -H "Authorization: Bearer $HANDWRITE_ACCESS_TOKEN"

Responses and recovery#

StatusMeaningFormat
200With your role in each.application/json
401unauthorized: no token, or it's invalid, revoked or expired.application/json
403insufficient_scope, forbidden (you can see it but not do this), app_test_restricted, account_deleted (the account is scheduled for deletion; any request).application/json
429rate_limited (burst or daily cap) or quota_exceeded (no characters left).application/json
500internal_error.application/json
Treat 403 as a current authority/policy failure and 404 as unavailable to this caller, without probing other accounts. Plan and seat checks may add 402 failures beyond generic reference responses. Retry only when the operation semantics permit it; keep Request-Id for support. Do not parse a 204 or 304 as JSON.
Read Team API specification notes, roles and access, and credential boundaries for the shared rules.
Modified at 2026-10-26 13:21:46
Next
README — POST /api/v1/orgs
Built with