1. Handwrite Regular Accounts
Handwrite
  • Handwrite Regular Accounts
    • Start here — Handwrite for outside developers
    • API specification notes
    • Socket specification notes
    • Account
      • README — GET /api/v1/me
      • README — DELETE /api/v1/me
      • README — GET /api/v1/me/policy
      • README — GET /api/v1/me/usage
      • Account API — README
      • Who this credential acts for
      • Delete the account (after a 30-day grace period)
      • What your teams' and classes' policies allow
      • Your own usage, and what your teams and classes counted
    • Documents
      • README — GET /api/v1/documents
      • README — POST /api/v1/documents
      • README — GET /api/v1/documents/search
      • README — GET /api/v1/documents/{id}
      • README — PATCH /api/v1/documents/{id}
      • README — DELETE /api/v1/documents/{id}
      • README — GET /api/v1/documents/{id}/content
      • README — PUT /api/v1/documents/{id}/content
      • README — POST /api/v1/documents/{id}/live
      • README — GET /api/v1/export
      • Documents API — README
      • List your documents (or shared, or changes since)
      • Create a document
      • Search your own and shared documents
      • A document's metadata
      • Change title, text, content type or language
      • Delete a document (owner)
      • The document's text
      • Replace the text
      • Join the document's live co-editing room
      • Every document you own, with its text
    • Files
      • README — GET /api/v1/documents/{id}/file
      • README — POST /api/v1/documents/{id}/file
      • README — POST /api/v1/documents/{id}/file/commit
      • README — POST /api/v1/documents/{id}/extract
      • Files API — README
      • Download the original file
      • Start uploading the original file
      • Make an uploaded file the document's file
      • Replace the text with the file's text
    • Audio
      • README — GET /api/v1/documents/{id}/audio
      • README — POST /api/v1/audio/stream
      • README — POST /api/v1/audio/speech
      • README — GET /api/v1/voices
      • README — GET /api/v1/quota
      • Audio API — README
      • The whole document as one audio file
      • Stream speech as it's made
      • Speech with word timings (read-along)
      • Voices you can use
      • Characters left, limit, plan and reset time
    • Sharing
      • README — GET /api/v1/documents/{id}/permissions
      • README — POST /api/v1/documents/{id}/permissions
      • README — PATCH /api/v1/documents/{id}/permissions/{principal}
      • README — DELETE /api/v1/documents/{id}/permissions/{principal}
      • README — DELETE /api/v1/documents/{id}/invitations/{inviteId}
      • README — GET /api/v1/invitations
      • README — POST /api/v1/invitations/{id}/accept
      • README — POST /api/v1/invitations/{id}/decline
      • Sharing API — README
      • Who a document is shared with
      • Share by principal, or invite by email (owner)
      • Change someone's role (owner)
      • Remove access (owner, or leave yourself)
      • Cancel a pending invitation (owner)
      • Document invitations to your verified email
      • Accept a document invitation
      • Decline a document invitation
    • Settings
      • README — GET /api/v1/settings
      • README — PATCH /api/v1/settings
      • Settings API — README
      • Synced app and reader settings
      • Change settings (per key, the newer updatedAt wins)
    • Webhooks
      • Incoming webhook delivery — README
      • README — GET /api/v1/webhooks
      • README — POST /api/v1/webhooks
      • README — GET /api/v1/webhooks/{id}
      • README — DELETE /api/v1/webhooks/{id}
      • Webhooks API — README
      • Your webhook endpoints
      • Register an endpoint (up to 10)
      • One endpoint
      • Delete an endpoint (queued retries are dropped)
    • Meta
      • README — GET /api/v1/openapi.json
      • Meta API — README
      • This OpenAPI description
    • OAuth
      • README — POST /api/oauth/token
      • README — POST /api/oauth/revoke
      • OAuth API — README
      • Exchange a code, or refresh
      • Revoke a token (RFC 7009)
    • Live socket
      • Live document socket — README
    • A document or sharing event
  1. Handwrite Regular Accounts

Start here — Handwrite for outside developers

Handwrite for outside developers#

Use Handwrite Cloud to build tools that read, search, edit, share and speak a person's documents. This documentation covers regular accounts. Team administration, classroom management, staff administration and internal service APIs have separate documentation areas.

Start here#

1.
Sign in at Account → Developer.
2.
For a private server-side integration, create a token with only the permissions your task needs. Save the value when shown and keep it in your server's secret store.
3.
For an app used by other people, register an OAuth app and use authorization code with PKCE. Each user authorizes their own account; do not distribute your personal API key.
4.
Check the identity, then work on a document the user has chosen.
curl --fail-with-body https://handwrites.io/api/v1/me \
  -H "Authorization: Bearer $HANDWRITE_API_KEY"

curl --fail-with-body 'https://handwrites.io/api/v1/documents?limit=20' \
  -H "Authorization: Bearer $HANDWRITE_API_KEY"
The first call returns principal and key; the second needs documents:read. A personal integration should see a user: principal. API keys authorize API calls; they do not create an interactive account sign-in session.

Choose an API#

AreaWhat you can build
AccountIdentify the authenticated principal and show the user's effective policy and usage.
DocumentsA document library, editor, search tool, incremental sync or export.
FilesUpload original files, download them and extract readable text.
SharingOwner-controlled sharing and an invitation inbox.
AudioRead-aloud, word highlighting, voice selection and downloadable speech.
SettingsSync reading preferences across supported devices.
WebhooksReact to document and permission changes on your server.
OAuthLet each person connect their own Handwrite account.
MetaFetch the full machine-readable OpenAPI description.
Each HTTP operation has an API reference and a separate README with its purpose, authentication, example, responses and integration notes. Read API specification notes for shared behavior and Socket specification notes before building collaborative editing.

App integration notes#

Account connection and document selection are separate actions. Connecting an account should not silently import every document. Let the user choose documents, or explicitly opt into library sync, and retain the chosen IDs. A fine-grained token can be restricted to chosen documents; handle access being removed later.
The API represents Handwrite Cloud data. Signing in does not grant direct access to a device's local files or its iCloud library. Show what your integration actually imported or synced; do not promise that every local or iCloud document appears in the Cloud API. Read app settings through the settings API; a stored preference does not mean every device supports the same feature.
Use a backend for a web integration: authenticated REST endpoints do not provide cross-origin browser CORS access. Never put a personal API key or confidential OAuth client secret into a distributed mobile app, browser bundle or URL. A public OAuth client uses PKCE and has no client secret. Store user tokens in appropriate secure storage and clear account-specific caches on disconnect.
Treat document text and uploaded files as user content. Ask before sharing, exporting or sending text for cloud speech. Show permission failures, quota exhaustion and sync conflicts as actionable states. Keep a local edit until the server has acknowledged it; never replace a newer document after a conflict without user reconciliation.

Testing and support#

Use a dedicated test account with disposable documents for write tests. An operator-issued app: test identity is isolated: it can only call GET /api/v1/me and GET /api/v1/voices, expires within 30 days and cannot exercise a user's library. It is not a general integration token or a substitute for OAuth consent.
Keep Request-Id when reporting API failures. Exclude tokens, signed download URLs, uploaded bytes and document text from diagnostics. The examples use placeholders, not working credentials. Authenticated calls and device behavior must be tested with your own authorized test account.
The reference was checked against the deployed OpenAPI description on 2026-10-26. The full description also includes organisation operations; this Regular Accounts edition omits those management routes.

Webhook compatibility snapshot — 2026-10-26#

The published OpenAPI still lists personal webhook registration. Current working-tree code instead rejects new personal receivers with 403 webhooks_moved; new receivers belong to teams/classes and are managed by an administrator in the organisation Developer tab. Existing personal receivers continue to receive events in that code. Deployment of this change and live runtime behavior were not verified here. Treat the registration reference as the published contract, not proof that new personal registration is available. The Team and Classroom editions describe the organisation workflow.
Modified at 2026-10-26 13:12:10
Next
API specification notes
Built with