1. Guides
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
      • Create a team or class
      • One of your organisations
      • Rename a team (owner or admin)
      • Delete with its memberships, invitations, documents and shares (owner)
    • 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. Guides

Team API specification notes

Base URL: https://handwrites.io. The team reference is a filtered edition of the shared Handwrite OpenAPI description, not a separate API version. JSON property names and route operation IDs match that description. Paths remain /api/v1/orgs; there is no invented /api/v1/teams alias.

Authentication and the request boundary#

Send Authorization: Bearer <credential> over HTTPS. The reference permits Handwrite API keys or OAuth access tokens. App/website session authentication is separate from an external integration and does not make private cookie-based console routes into public APIs.
orgs:read is needed for organisation reads; orgs:manage for organisation writes; listing an organisation's documents uses documents:read. Scope checks are followed by current membership/role, plan, policy and selected-document checks. A valid token may therefore return 403 or see fewer documents. A non-member organisation lookup returns 404 to avoid revealing it. Never interpret 404 as proof an ID does not exist globally.
URL-encode full principals in path segments, for example user%3A…. Keep org_…, doc_…, invitation IDs and token IDs distinct. Do not strip a principal prefix or substitute an email where the contract requires a principal.

HTTP behavior#

ConcernContract and app behavior
JSONSend Content-Type: application/json for JSON bodies. Use only supported fields; runtime validators may be stricter than a generated client type.
CorrelationKeep Request-Id for support without retaining tokens or user content.
Rate limitsRespect Retry-After on 429 and returned Handwrite-Requests-* headers. Daily counting is per credential/account under the global cap. The stored dailyRequests organisation policy is not currently used by that counter; monthly audio policy is a separate control.
ErrorsJSON errors use error.code and error.message. Generic authentication/validation/server errors and endpoint-specific errors both apply.
Empty success204 has no body. Live usage may return 304 with no body after If-None-Match.
CSVOrganisation usage with format=csv is a file/text response, not JSON.
PaginationFollow opaque document cursors until null, even if filtering yields an empty page. Do not invent offsets or persist a partially completed sync as complete.
Changessince lists changed team-owned documents including tombstones. Keep IDs and revisions; periodic full reconciliation is needed if your checkpoint falls beyond retained tombstones.
ReplacementPolicy PUT replaces the stored rule map. Read and merge the user's intended edits before writing; it is not JSON Merge Patch.

Retrying writes#

The contract exposes Idempotency-Key for creating an organisation, adding a member and creating an invitation. Use a new random key for each logical action and reuse it only for an identical retry. A replay is not a license to change the body while retaining the key. Follow the shared API's idempotency error semantics.
Do not blindly replay role transfers, destructive deletes or policy replacements after a network timeout. Re-read the affected state and decide whether the original operation succeeded. A delete or leave operation succeeding does not authorize repeating other side effects in your app. Show 402 plan/seat failures as capacity or entitlement issues, not transient network errors. Do not retry 403 to evade policy.
For document editing, use the shared API notes and its revision/If-Match rules. Keep unsaved edits on 409 live_session_active or 412 and reconcile them explicitly.

Scope of this reference#

These 30 organisation operations have a README each. Shared document/file/audio/settings/OAuth APIs stay in Regular Accounts. Team SSO setup, billing mutations, audit/export UI and Developer-tab setup use Handwrite's cookie-session portal; their private /api/org handlers are implementation details rather than supported outside-developer endpoints. See SSO and portal workflows.
Source: reviewed src/cloud/openapi.ts snapshot, src/app/api/v1/orgs/**, http.ts, orgs.ts, org-invites.ts, policies.ts, managed-tokens.ts, usage-org.ts and insights.ts. Schemas describe the published contract; source-only additions and unverified release state are identified in the app guide.
Modified at 2026-10-26 13:24:10
Previous
Start here — Team app integration
Next
Team socket specification notes
Built with