Start uploading the original file

POST

/api/v1/documents/{id}/file

PUT the bytes to the returned url with the returned headers (no API key), then POST /file/commit.

App integration: This only reserves an upload. PUT the actual bytes to the returned URL with its returned headers, then call commitUpload with the same file metadata and uploadId. Do not forward your API token to storage. Re-request a reservation if its 900-second URL expires.

Request

Authorization

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

OAuth 2.0

Authorization Code

Add the parameter

Authorization

to Headers，whose value is to concatenate the Token after the Bearer.

Example:

Authorization: Bearer ********************

Authorize URL: https://handwrites.io/oauth/authorize

Token URL: https://handwrites.io/api/oauth/token

Refresh URL: https://handwrites.io/api/oauth/token

Scopes:

documents:write-Create documents, edit them and upload their files

Path Params

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢201

application/json

Where to PUT the file.

Headers

Bodyapplication/json

🟠400BadRequest

🟠401Unauthorized

🟠403Forbidden

🟠404NotFound

🟠409Conflict

🟠422Unprocessable

🟠429TooManyRequests

🔴500ServerError

Request Example

Shell

JavaScript

Java

Swift

curl --location '/api/v1/documents//file' \
--header 'Idempotency-Key;' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "name": "string",
    "type": "application/pdf",
    "length": 1
}'

Response Example

201 - Example 1

{
    "uploadId": "string",
    "url": "http://example.com",
    "method": "PUT",
    "headers": {
        "property1": "string",
        "property2": "string"
    },
    "expiresIn": 0
}

Modified at 2026-10-26 12:58:15

Download the original file

Make an uploaded file the document's file