For Developers
      Back to home
      1. Help Center
      2. For Developers

      Transkribus Legacy API

      The Transkribus API described below is a legacy system that has been in use for many years. While it remains functional, we do not provide support for this API, as its documentation is incomplete and outdated.

      In 2025, we will gradually introduce new, modern APIs to replace this legacy system. These new APIs will be better documented, more robust, and designed to meet current development standards. We recommend transitioning to the new APIs as they become available.

      Legacy API Overview

      The Transkribus application communicates with the server through a set of RESTful service methods. The full definition of these methods can be found in the application.wadl file and visualized using SWADL. Below is a summary of the main API functionalities.

      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=transkribus-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=transkribus-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. Using the Access Token to authorize requests

      When sending any of the requests below, the current access token must be attached in the request headers:

      • Header Name: Authorization
      • Header Value: Bearer $ACCESS_TOKEN
      For example, the following request would get the list of collections accessible to the authenticated user:
      curl -H "Authorization: Bearer $ACCESS_TOKEN" https://transkribus.eu/TrpServer/rest/collections

      4. 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

      Collections

      Authenticated users can list their accessible collections:

      GET https://transkribus.eu/TrpServer/rest/collections

      This request returns a list of collections, including collection IDs, names, and user roles.

      To list documents within a collection:

      GET https://transkribus.eu/TrpServer/rest/collections/{collection-ID}/list

      To retrieve a complete document:

      GET https://transkribus.eu/TrpServer/rest/collections/{collection-ID}/{document-ID}/fulldoc

      Transcription Updates

      To update a PAGE XML file for a document page:

      POST https://transkribus.eu/TrpServer/rest/collections/{collection-ID}/{doc-ID}/{pageNr}/text

      Query parameters:

      • status: The edit status (e.g., NEW, IN_PROGRESS, DONE, FINAL)

      • overwrite: Whether to overwrite the recent version (only allowed under specific conditions)

      Job Processing

      Processing tasks such as document creation, layout analysis, and OCR are handled as jobs.

      To list active jobs:

      GET https://transkribus.eu/TrpServer/rest/jobs/list

      To check a specific job:

      GET https://transkribus.eu/TrpServer/rest/jobs/{job-ID}

      To cancel a job:

      POST https://transkribus.eu/TrpServer/rest/jobs/{job-ID}/kill

      To retrieve error details for a job:

      GET https://transkribus.eu/TrpServer/rest/jobs/{job-ID}/errors

      Full-Text Search

      To search recognized text using SOLR indexing:

      GET https://transkribus.eu/TrpServer/rest/search/fulltext?query=XXX&type=LinesLc&filter=collectionId:1234

      Query parameters:

      • query: The search string

      • type: Defines the scope of the search (e.g., "LinesLc" searches recognized text without case sensitivity)

      • filter: Filters results by collection ID

      Future Development

      As we move towards a modern API structure, we strongly encourage developers to prepare for migration to the upcoming APIs. The new APIs will be fully documented, actively maintained, and optimized for reliability and performance.

      We appreciate your patience and cooperation during this transition period. More details on the new APIs will be provided in 2025.

      For updates, please refer to the official Transkribus communication channels.