Metagrapho Documentation


The Transkribus API facilitates the processing of images using the Transkribus HTR (Handwritten Text Recognition) technology. With this API, users can submit images for processing and later retrieve results using the provided processId.


To interact with the Transkribus API, you must first authenticate to obtain an access token. The API uses the OpenID Connect protocol for authentication. Here's a step-by-step guide to obtaining and managing your access tokens.

For some libraries, you might require the OpenID Connect configuration URL, which is available at:

1. Obtain an Access Token

Use the following cURL command, replacing $USERNAME and $PASSWORD with your credentials:

curl --location --request POST \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode grant_type=password \
--data-urlencode username=$USERNAME \
--data-urlencode password=$PASSWORD \
--data-urlencode client_id=processing-api-client

Upon successful authentication, you will receive an access token in the response. Additionally, youll receive a refresh token that can be used to obtain a new access token once the current one expires.

2. Refreshing the Access Token

If your access token expires, you can use the provided refresh token to obtain a new one with this command:

curl --location --request POST \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode grant_type=refresh_token \
--data-urlencode client_id=processing-api-client \
--data-urlencode refresh_token=$REFRESH_TOKEN

Replace $REFRESH_TOKEN with your refresh token. Update your refresh token if the response contains a new one.

3. Ending the Session

To log out and invalidate the refresh token, use:

curl --location --request POST \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode refresh_token=$REFRESH_TOKEN \
--data-urlencode client_id=processing-api-client

Billing Information

By default, the Transkribus API utilizes the internal Credit-System of Transkribus for billing. However, upon request, a Pay-Per-Use billing system can be arranged.


Pages submitted to the endpoint remain accessible for up to 2 days. After this period, you will receive a `404 Not Found` response if trying to access them.

Images or pages arent immediately deleted after the Handwritten Text Recognition (HTR) process. They follow the same 2-day retention policy as mentioned above.

Yes, the pricing model is different due to the non-reliance on storage capacity. For a detailed breakdown, please refer to the following document.

As of version ≥ 0.8.0, the same restrictions on model usage are applied as on the Transkribus platform. This means that API accounts need to be added to collections where private models are linked to for access.