1. Files
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
        GET
      • Start uploading the original file
        POST
      • Make an uploaded file the document's file
        POST
      • Replace the text with the file's text
        POST
    • 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. Files

README — POST /api/v1/documents/{id}/file/commit

Make an uploaded file the document's file#

POST /api/v1/documents/{id}/file/commit · Operation ID: commitUpload

Purpose and app behavior#

Call after the storage PUT succeeds. Use the matching uploadId, name, type and byte length and the latest If-Match revision. Inspect extracted: a successful commit can still report an extraction error while retaining the original file.
If the document has no text, the file's text is extracted at once and reported in extracted.

Authentication#

Bearer token with documents:write. Resource access and effective policy still apply.

Example request#

Replace all REPLACE_* placeholders and environment values with data for your authorized test account. Use a new UUID in IDEMPOTENCY_KEY for each logical action where shown; use the actual latest revision for If-Match. Examples of writes change real data if run.
curl --fail-with-body -X POST 'https://handwrites.io/api/v1/documents/REPLACE_DOCUMENT_ID/file/commit' \
  -H "Authorization: Bearer $HANDWRITE_API_KEY" \
  -H 'If-Match: "REPLACE_REVISION"' \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"uploadId":"REPLACE_UPLOAD_ID","name":"notes.txt","type":"text/plain","length":23}'

Parameters#

NameLocationRequiredMeaning
idpathYesA document ID (doc_…).
If-MatchheaderNoThe revision you last saw, like "3"; 412 if the document has moved on.
Idempotency-KeyheaderNo1–255 visible ASCII characters (a UUID per operation). A retry with the same key and identical request within 24 hours replays the first 2xx response with Idempotent-Replayed: true; a different request with the key gets 422 idempotency_mismatch; a retry while the first runs gets 409 idempotency_in_progress.

Request body#

application/json (required).
The paired API reference defines the complete schema and alternatives.

Responses#

StatusMeaningBody format
200The new revision.application/json
400invalid_request (the message names the field), validation_failed.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
409conflict (changed meanwhile, already a member) or idempotency_in_progress (with Retry-After).application/json
412revision_mismatch: If-Match didn't match; ETag has the current revision.application/json
422limit_reached, idempotency_mismatch, unreadable_file, no_text, empty_document.application/json
429rate_limited (burst or daily cap) or quota_exceeded (no characters left).application/json
500internal_error.application/json
Use the paired API reference for complete request/response schemas. See API specification notes for rate limits, error handling, safe retries and additional policy/plan failures. For binary or empty responses, do not call a JSON parser.
Modified at 2026-10-26 13:00:02
Previous
README — POST /api/v1/documents/{id}/file
Next
README — POST /api/v1/documents/{id}/extract
Built with