Appearance
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
| Object | What it is |
|---|---|
| Dataset | The container: name, description, visibility, owner. Lifecycle operations make it citable (a DOI) or withdraw it. |
| Version | A 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. |
| Item | One page of one document, with its transcript. Items are added from your collections, from model training data or from ground-truth references. |
| Split | Every item in a version belongs to the train, validation or test split. Splits are set per item, by percentage, or automatically. |
| Access | Datasets 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
GET
https://api-dataset.transkribus.org/v1/datasetsCreate new dataset
POST
https://api-dataset.transkribus.org/v1/datasetsRead a dataset and its versions.
Get dataset with latest version
GET
https://api-dataset.transkribus.org/v1/datasets/{id}List all versions for a dataset
GET
https://api-dataset.transkribus.org/v1/datasets/{id}/versionsRead the items of a version.
List items in a version (filterable by split)
GET
https://api-dataset.transkribus.org/v1/datasets/{id}/versions/{vid}/itemsReturns 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
Requiredinteger
vid*
Version ID (must belong to the dataset given in id)
Type
Requiredinteger
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
100offset
Number of items to skip (pagination)
Type
integer
Default
0Responses
Items retrieved successfully
application/json
Total number of matching items (ignores limit/offset)
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.