Skip to content

Datasets ​

A dataset is a curated set of transcribed pages, used as training data or published as a citable research output. Datasets close the loop: corrected results become training material, which becomes models that perform better on your documents. The Dataset API creates datasets, manages their versions, items and splits, and hands training data to model training.

Authentication is the same as for every other API: a Transkribus account and a Bearer token, see Authentication. The operations a first integration needs are on this page; every other operation is in the groups beneath this page in the sidebar.

How a dataset is organised ​

ObjectWhat it is
DatasetThe container: name, description, visibility, owner. Lifecycle operations make it citable (a DOI) or withdraw it.
VersionA dataset has versions. The current one takes changes; a frozen version is immutable and is what training and citation refer to. Versions can be copied, whole or by split.
ItemOne page of one document, with its transcript. Items are added from your collections, from model training data or from ground-truth references.
SplitEvery item in a version belongs to the train, validation or test split. Splits are set per item, by percentage, or automatically.
AccessDatasets are shared by access grants to users or groups; ownership can be transferred; an audit log records changes.

Working with a dataset ​

List your datasets and create one.

List user's datasets ​

GEThttps://api-dataset.transkribus.org/v1/datasets
Try it out

Playground​

Authorization

Samples​

Create new dataset ​

POSThttps://api-dataset.transkribus.org/v1/datasets

Request Body​

application/json

Dataset name

Dataset description (supports HTML)

Digital Object Identifier for academic citation (format 10.xxxx/xxxxx)

Owner user ID

Try it out

Playground​

Authorization
Body

Samples​

Read a dataset and its versions.

Get dataset with latest version ​

GEThttps://api-dataset.transkribus.org/v1/datasets/{id}

Parameters​

Path Parameters

id*
Type
string
Required
Try it out

Playground​

Authorization
Variables
Key
Value

Samples​

List all versions for a dataset ​

GEThttps://api-dataset.transkribus.org/v1/datasets/{id}/versions

Parameters​

Path Parameters

id*
Type
string
Required
Try it out

Playground​

Authorization
Variables
Key
Value

Samples​

Read the items of a version.

List items in a version (filterable by split) ​

GEThttps://api-dataset.transkribus.org/v1/datasets/{id}/versions/{vid}/items

Returns the items linked to a version. Requires read access to the
dataset (owner, admin, an explicit access grant, or a public dataset).

This response is paginated and limit defaults to 100. Items come
back ordered by row id, and whether a given split appears in the first
page depends on the order the items happened to be inserted — a version
with thousands of validation items can answer an unpaginated request
with train items only. Always compare data.length against total,
and page until you have total rows. To ask about one split, filter
with split= rather than scanning an unfiltered page: total is then
the exact count for that split. GET .../versions/{vid}/splits returns
per-split counts directly and is not subject to pagination at all.

Parameters​

Path Parameters

id*

Dataset (definition) ID

Type
integer
Required
vid*

Version ID (must belong to the dataset given in id)

Type
integer
Required

Query Parameters

split

Optional split filter

Type
string
Valid values
"train""validation""test"
limit

Max number of items to return. Defaults to 100 when omitted — pass
an explicit value to get more. 0 is treated as omitted (falls back
to 100) and negative values are rejected by the database, so page
with a real page size instead of trying to disable the limit.

Type
integer
Default
100
offset

Number of items to skip (pagination)

Type
integer
Default
0

Responses​

Items retrieved successfully

application/json

Total number of matching items (ignores limit/offset)

Try it out

Playground​

Authorization
Variables
Key
Value

Samples​

What the reference leaves out ​

The admin review queue for citable datasets, and the health and test endpoints, are not part of the developer platform and are left out of the sidebar.

Transkribus Developer Platform