HandwritingOCR Documentation

Postman collection → OpenAPI spec →

Introduction

This documentation aims to provide all the information you need to work with our API.

Authenticating requests

To authenticate requests, include an Authorization header with the value "Bearer {YOUR_AUTH_KEY}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

You can enable API access and generate your token by visiting the settings page in the account dashboard.

Document Management

APIs for managing documents

List documents

GET
https://www.handwritingocr.com
/api/v1/documents
requires authentication

Get a paginated list of the authenticated user's documents.

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

Query Parameters

page
integer

The page number. Default: 1

Example:
20
per_page
integer

The number of items per page. Default: 50

Example:
6
Example request: 
curl --request GET \
    --get "https://www.handwritingocr.com/api/v1/documents?page=20&per_page=6" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "current_page": 1,
    "data": [
        {
            "document_id": "abc123",
            "status": "processed",
            "created_at": "2023-05-01T12:00:00Z",
            "updated_at": "2023-05-01T12:30:00Z",
            "automatically_deleted_at": "2023-05-08T12:00:00Z",
            "page_count": 5,
            "original_file_name": "example.pdf",
            "action": "transcribe"
        }
    ],
    "first_page_url": "http://www.handwritingocr.com/api/v1/documents?page=1",
    "from": 1,
    "last_page": 1,
    "last_page_url": "http://www.handwritingocr.com/api/v1/documents?page=1",
    "links": [
        {
            "url": null,
            "label": "« Previous",
            "active": false
        },
        {
            "url": "http://www.handwritingocr.com/api/v1/documents?page=1",
            "label": "1",
            "active": true
        },
        {
            "url": null,
            "label": "Next »",
            "active": false
        }
    ],
    "next_page_url": null,
    "path": "http://www.handwritingocr.com/api/v1/documents",
    "per_page": 50,
    "prev_page_url": null,
    "to": 1,
    "total": 1
}

Process a new document

POST
https://www.handwritingocr.com
/api/v1/documents
requires authentication

Upload a new document for processing.

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
multipart/form-data
Accept
Example:
application/json

Body Parameters

Example request: 
curl --request POST \
    "https://www.handwritingocr.com/api/v1/documents" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: multipart/form-data" \
    --header "Accept: application/json" \
    --form "action=id"\
    --form "extractor_id=19"\
    --form "delete_after=14"\
    --form "file=@/private/var/folders/xt/b28shz4965d33r0h9hpysjzh0000gn/T/phpKIyKgK"
Example response:
{
    "document_id": "abc123",
    "status": "queued"
}
{
    "errors": {
        "file": [
            "The file field is required."
        ],
        "action": [
            "The action field is required."
        ]
    }
}

Get document details

GET
https://www.handwritingocr.com
/api/v1/documents/{id}
requires authentication

Retrieve details of a specific document.

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

id
string
required

The document's id.

Example:
aut
Example request: 
curl --request GET \
    --get "https://www.handwritingocr.com/api/v1/documents/aut" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "id": "abc123",
    "status": "processed",
    "action": "transcribe",
    "created_at": "2023-05-01T12:00:00Z",
    "updated_at": "2023-05-01T12:30:00Z",
    "results": {
        "txt": "https://www.handwritingocr.com/api/v1/documents/abc123/download/token123/transcribe.txt",
        "docx": "https://www.handwritingocr.com/api/v1/documents/abc123/download/token123/transcribe.docx",
        "json": "https://www.handwritingocr.com/api/v1/documents/abc123/download/token123/transcribe.json"
    }
}
{
    "message": "Document abc123 was not found"
}

Delete a document

DELETE
https://www.handwritingocr.com
/api/v1/documents/{id}
requires authentication

Delete a specific document and its associated file.

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

id
string
required

The document's id.

Example:
laborum
Example request: 
curl --request DELETE \
    "https://www.handwritingocr.com/api/v1/documents/laborum" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
[Empty response]
{
    "message": "No query results for model [App\\Models\\Document] abc123"
}

Download processed document

GET
https://www.handwritingocr.com
/api/v1/documents/{id}/download/{token}/{action}.{format}
requires authentication

Download a processed document in the specified format.

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

id
string
required

The document's id.

Example:
vel
token
string
required

The download token.

Example:
harum
action
string
required

The processing action. Must be one of: transcribe, tables, extractor.

Example:
quo
format
string
required

The download format. Available formats depend on the action.

Example:
eligendi
Example request: 
curl --request GET \
    --get "https://www.handwritingocr.com/api/v1/documents/vel/download/harum/quo.eligendi" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
 "binary_file_content"
}
{
    "error": "Invalid or expired download token"
}