Introduction

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.

Authentication

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: https://account.readcoop.eu/auth/realms/readcoop/.well-known/openid-configuration

1. Obtain an Access Token

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

curl --location --request POST https://account.readcoop.eu/auth/realms/readcoop/protocol/openid-connect/token \
--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 https://account.readcoop.eu/auth/realms/readcoop/protocol/openid-connect/token \
--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 https://account.readcoop.eu/auth/realms/readcoop/protocol/openid-connect/logout \
--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.