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/{id}

One of your organisations#

GET /api/v1/orgs/{id} · Operation ID: getOrg

App purpose#

Read the role from the returned team snapshot. Do not infer authority from a cached UI role; every later action checks current membership and role again.

Authentication and authority#

Bearer credential with orgs:read. A current member; non-members receive 404.
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/REPLACE_TEAM_ID' \
  -H "Authorization: Bearer $HANDWRITE_ACCESS_TOKEN"

Parameters#

NameInRequiredMeaning
idpathYesAn organisation ID (org_…).

Responses and recovery#

StatusMeaningFormat
200The organisation.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
404not_found: it doesn't exist or you can't see it (never 403 for documents you can't see).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
Previous
README — POST /api/v1/orgs
Next
README — PATCH /api/v1/orgs/{id}
Built with