Create a document

POST

/api/v1/documents

App integration: Create only after the user chooses to add/import content. In the personal workflow omit owner; an organisation owner requires separate management permissions. Save the returned ID and revision. Reuse an Idempotency-Key only for an identical retry of this creation.

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

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢201

application/json

Created at revision 1.

Headers

Bodyapplication/json

🟠400BadRequest

🟠401Unauthorized

🟠403Forbidden

🟠404NotFound

🟠409Conflict

🟠413TooLarge

🟠422Unprocessable

🟠429TooManyRequests

🔴500ServerError

Request Example

Shell

JavaScript

Java

Swift

curl --location '/api/v1/documents' \
--header 'Idempotency-Key;' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "title": "string",
    "content": "",
    "contentType": "text/plain",
    "language": "en",
    "owner": "string"
}'

Response Example

201 - Example 1

{
    "id": "doc_Ab3dEf6hIj9kLm0n",
    "title": "string",
    "language": "en",
    "revision": 0,
    "contentType": "text/plain",
    "contentLength": 0,
    "contentSha256": "string",
    "file": {
        "name": "string",
        "type": "application/pdf",
        "length": 0
    },
    "owner": "user:3f2b…",
    "access": "owner",
    "source": "api",
    "createdAt": "2019-08-24T14:15:22.123Z",
    "updatedAt": "2019-08-24T14:15:22.123Z"
}

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

List your documents (or shared, or changes since)

Search your own and shared documents