Skip to content

Sites ​

A site is a public, searchable presentation of a collection: an institution publishes material it has transcribed in Transkribus, and anyone can browse and search it on the web. The Sites API creates and edits sites and searches their documents. The operations a first integration needs are on this page; every other operation is in the V2 Sites and Search groups beneath this page in the sidebar.

Authentication is the same as for every other API: a Transkribus account and a Bearer token, see Authentication.

How a site is organised ​

ObjectWhat it is
SiteThe published presentation, identified by an id and by its URL slug. Owns the collection ids it shows, a title, a description, a theme and images.
VersionA site has one draft version and, once published, one published version. Edits go to the draft; publishing makes it the live version. Any earlier version can be restored into a new draft.
PageA version holds pages. Each page has settings and an ordered list of blocks.
BlockA unit of page content: text, images and other kinds. Blocks can be created, updated, reordered and deleted on the draft version only.

Working with a site ​

  1. Create the site with POST /v2/sites: URL slug, owner, title, description and the collection ids. This also creates the first draft version with a home page and a hero block.
  2. Edit the draft: list its pages, add or update pages and blocks, upload images for the site or for a block.
  3. Publish the draft with POST /v2/sites/{siteId}/versions/{versionId}/publish. The draft becomes the published version; a new draft starts from it.
  4. Read a site the way a visitor does, by URL: GET /v2/sites/by-url/{url} for the site, .../pages/{pageKey} for a page, .../documents for the documents it shows.

Sites also expose statistics (GET /v2/sites/{siteId}/stats) and a changelog per version.

Create a site. The slug becomes the site's public URL; colId lists the collections it shows; userId is the numeric id of the Transkribus account that owns the site. The response carries the site with its id and its first draft version; pages and blocks are addressed under that version until you publish it.

Create a new site with initial draft version ​

POSThttps://api-sites.transkribus.eu/v2/sites

Creates a site AND its first draft version with default home page and hero block

Request Body​

application/json

Unique site URL/slug

Owner user ID

Site title

Site description

Collection IDs (required)

Site configuration

Responses​

Site created with initial draft

Try it out

Playground​

Authorization
Body

Samples​

Publish the draft. The draft becomes the published version and a new draft starts from it.

Publish the draft version ​

POSThttps://api-sites.transkribus.eu/v2/sites/{siteId}/versions/{versionId}/publish
  1. Sets current published version to 'frozen'
  2. Promotes draft to 'published' with new versionNumber
  3. Creates new draft (copy of published)

Parameters​

Path Parameters

siteId*

The site ID

Type
integer
Required
versionId*

The draft version ID to publish

Type
integer
Required

Responses​

Published successfully

Try it out

Playground​

Authorization
Variables
Key
Value

Samples​

Read a site as a visitor does, by URL slug, no token needed for a published site.

Get site by URL slug ​

GEThttps://api-sites.transkribus.eu/v2/sites/by-url/{url}

Parameters​

Path Parameters

url*

Site URL slug

Type
string
Required

Responses​

Site found

Try it out

Playground​

Authorization
Variables
Key
Value

Samples​

Get page by site URL and page key ​

GEThttps://api-sites.transkribus.eu/v2/sites/by-url/{url}/pages/{pageKey}

Parameters​

Path Parameters

url*

Site URL slug

Type
string
Required
pageKey*

Page key/slug

Type
string
Required

Query Parameters

published

Get published version (default is draft)

Type
boolean

Responses​

Page found with site and version info

Try it out

Playground​

Authorization
Variables
Key
Value

Samples​

The Search operations query the documents of a site: full-text search with facets and hierarchy, pages of a document, tags and tag definitions, and the collections and documents a site shows. They are scoped by the site URL, so a search only ever sees what that site publishes.

What the reference leaves out ​

The Sites API also serves the web app's v1 routes, hidden pages, analytics and the v1-to-v2 migration. They are not part of the developer platform and are left out of the sidebar.

Transkribus Developer Platform