Appearance
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
| Object | What it is |
|---|---|
| Site | The 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. |
| Version | A 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. |
| Page | A version holds pages. Each page has settings and an ordered list of blocks. |
| Block | A 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
- 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. - Edit the draft: list its pages, add or update pages and blocks, upload images for the site or for a block.
- Publish the draft with
POST /v2/sites/{siteId}/versions/{versionId}/publish. The draft becomes the published version; a new draft starts from it. - Read a site the way a visitor does, by URL:
GET /v2/sites/by-url/{url}for the site,.../pages/{pageKey}for a page,.../documentsfor 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
POST
https://api-sites.transkribus.eu/v2/sitesPublish the draft. The draft becomes the published version and a new draft starts from it.
Publish the draft version
POST
https://api-sites.transkribus.eu/v2/sites/{siteId}/versions/{versionId}/publishRead a site as a visitor does, by URL slug, no token needed for a published site.
Get site by URL slug
GET
https://api-sites.transkribus.eu/v2/sites/by-url/{url}Get page by site URL and page key
GET
https://api-sites.transkribus.eu/v2/sites/by-url/{url}/pages/{pageKey}Search
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.