LAUDATIO-Repository REST API

openapi: 3.0.3
x-method: derived
x-generated: '2026-09-01'
x-source: https://www.laudatio-repository.org/docs/elasticapi
x-operator: institution
x-authored-by: API Evangelist — NOT published by Humboldt-Universitaet zu Berlin
info:
  title: LAUDATIO-Repository REST API (Humboldt-Universität zu Berlin)
  description: >-
    Public, read-only REST API of the LAUDATIO-Repository (Long-term Access and Usage of
    Deeply Annotated Information), the open-access research-data repository for historical
    linguistic corpora operated by the Department of Corpus Linguistics (Institut für
    deutsche Sprache und Linguistik) together with the Computer- und Medienservice (CMS) of
    Humboldt-Universität zu Berlin.

    The API exposes the published and indexed Corpus, Document and Annotation header
    metadata held in the repository's Elasticsearch index. Every response is wrapped in a
    {success, data, message, status} envelope; `data` carries raw Elasticsearch hits.

    OPERATOR: institution. Although the service runs on the laudatio-repository.org domain
    rather than hu-berlin.de, every ownership signal resolves to HU Berlin — the site
    imprint and privacy policy link to https://www.hu-berlin.de/de/hu/impressum, sign-in
    offers "HU-account" authentication against the HU Shibboleth IdP, the source code is
    hosted on HU's own GitLab at https://scm.cms.hu-berlin.de/hu-berlin-laudatio-repository,
    and its DOIs are minted under HU Berlin's DataCite membership as repository
    tib.hu-laudatio.

    PROVENANCE: this description was NOT published by Humboldt-Universität zu Berlin. It was
    authored by API Evangelist from the repository's own published API reference at
    https://www.laudatio-repository.org/docs/elasticapi (which enumerates all 32 documented
    paths) and verified against live responses on 2026-09-01. HU publishes the reference in
    prose and code samples; it publishes no OpenAPI of its own.
  version: v1
  contact:
    name: LAUDATIO-Repository, Korpuslinguistik & Computer- und Medienservice, Humboldt-Universität zu Berlin
    url: https://www.laudatio-repository.org/contact
  termsOfService: https://www.hu-berlin.de/de/hu/impressum
servers:
  - url: https://www.laudatio-repository.org
    description: LAUDATIO-Repository production
tags:
  - name: Corpora
    description: Published historical corpora and their header metadata
  - name: Documents
    description: Documents belonging to a published corpus
  - name: Annotations
    description: Annotation layers and their preparation metadata
paths:
  /api/elasticapi/v1/corpora:
    get:
      tags: [Corpora]
      summary: List all indexed corpora
      description: Returns every corpus header record held in the Elasticsearch index.
      operationId: listCorpora
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
      responses:
        '200':
          description: Envelope carrying Elasticsearch corpus hits
          content:
            application/json:
              schema: { $ref: '#/components/schemas/HitListEnvelope' }
  /api/elasticapi/v1/corpora/latest/count:
    get:
      tags: [Corpora]
      summary: Count the latest published corpora
      operationId: countLatestCorpora
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
      responses:
        '200':
          description: Count envelope
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CountEnvelope' }
              example:
                success: true
                data: '{"count":30,"_shards":{"total":1,"successful":1,"skipped":0,"failed":0}}'
                message: ' Latest corpora count retrieved successfully.'
                status: 200
                count: 30
  /api/elasticapi/v1/corpora/latest/{from}/{size}:
    get:
      tags: [Corpora]
      summary: Page through the latest published corpora
      operationId: listLatestCorpora
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/From'
        - $ref: '#/components/parameters/Size'
      responses:
        '200':
          description: Envelope carrying a page of corpus hits
          content:
            application/json:
              schema: { $ref: '#/components/schemas/HitListEnvelope' }
  /api/elasticapi/v1/corpora/latest/searchMain:
    get:
      tags: [Corpora]
      summary: Search the latest published corpora
      operationId: searchLatestCorpora
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
      responses:
        '200':
          description: Envelope carrying matching corpus hits
          content:
            application/json:
              schema: { $ref: '#/components/schemas/HitListEnvelope' }
  /api/elasticapi/v1/corpora/latest/searchMain/count:
    get:
      tags: [Corpora]
      summary: Count corpora matching the main search
      operationId: countSearchLatestCorpora
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
      responses:
        '200':
          description: Count envelope
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CountEnvelope' }
  /api/elasticapi/v1/corpora/{id}/{index}:
    get:
      tags: [Corpora]
      summary: Retrieve one corpus by Elasticsearch id and index
      operationId: getCorpus
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/Id'
        - $ref: '#/components/parameters/Index'
      responses:
        '200':
          description: Envelope carrying the corpus hit
          content:
            application/json:
              schema: { $ref: '#/components/schemas/HitListEnvelope' }
  /api/elasticapi/v1/corpora/{id}/{index}/documents:
    get:
      tags: [Corpora]
      summary: List the documents of one corpus
      operationId: getCorpusDocuments
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/Id'
        - $ref: '#/components/parameters/Index'
      responses:
        '200':
          description: Envelope carrying document hits
          content:
            application/json:
              schema: { $ref: '#/components/schemas/HitListEnvelope' }
  /api/elasticapi/v1/corpora/{id}/{index}/annotations:
    get:
      tags: [Corpora]
      summary: List the annotation layers of one corpus
      operationId: getCorpusAnnotations
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/Id'
        - $ref: '#/components/parameters/Index'
      responses:
        '200':
          description: Envelope carrying annotation hits
          content:
            application/json:
              schema: { $ref: '#/components/schemas/HitListEnvelope' }
  /api/elasticapi/v1/documents:
    get:
      tags: [Documents]
      summary: List all indexed documents
      operationId: listDocuments
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
      responses:
        '200':
          description: Envelope carrying document hits
          content:
            application/json:
              schema: { $ref: '#/components/schemas/HitListEnvelope' }
  /api/elasticapi/v1/documents/latest/count:
    get:
      tags: [Documents]
      summary: Count the latest published documents
      operationId: countLatestDocuments
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
      responses:
        '200':
          description: Count envelope
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CountEnvelope' }
              example:
                success: true
                data: '{"count":5284,"_shards":{"total":1,"successful":1,"skipped":0,"failed":0}}'
                message: ' Latest documents count retrieved successfully.'
                status: 200
                count: 5284
  /api/elasticapi/v1/documents/latest/{from}/{size}:
    get:
      tags: [Documents]
      summary: Page through the latest published documents
      operationId: listLatestDocuments
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/From'
        - $ref: '#/components/parameters/Size'
      responses:
        '200':
          description: Envelope carrying a page of document hits
          content:
            application/json:
              schema: { $ref: '#/components/schemas/HitListEnvelope' }
  /api/elasticapi/v1/documents/latest/searchMain:
    get:
      tags: [Documents]
      summary: Search the latest published documents
      operationId: searchLatestDocuments
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
      responses:
        '200':
          description: Envelope carrying matching document hits
          content:
            application/json:
              schema: { $ref: '#/components/schemas/HitListEnvelope' }
  /api/elasticapi/v1/documents/latest/searchMain/count:
    get:
      tags: [Documents]
      summary: Count documents matching the main search
      operationId: countSearchLatestDocuments
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
      responses:
        '200':
          description: Count envelope
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CountEnvelope' }
  /api/elasticapi/v1/documents/{id}/{index}:
    get:
      tags: [Documents]
      summary: Retrieve one document by Elasticsearch id and index
      operationId: getDocument
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/Id'
        - $ref: '#/components/parameters/Index'
      responses:
        '200':
          description: Envelope carrying the document hit
          content:
            application/json:
              schema: { $ref: '#/components/schemas/HitListEnvelope' }
  /api/elasticapi/v1/documents/{id}/{index}/annotations:
    get:
      tags: [Documents]
      summary: List the annotation layers of one document
      operationId: getDocumentAnnotations
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/Id'
        - $ref: '#/components/parameters/Index'
      responses:
        '200':
          description: Envelope carrying annotation hits
          content:
            application/json:
              schema: { $ref: '#/components/schemas/HitListEnvelope' }
  /api/elasticapi/v1/annotations:
    get:
      tags: [Annotations]
      summary: List all indexed annotation layers
      operationId: listAnnotations
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
      responses:
        '200':
          description: Envelope carrying annotation hits
          content:
            application/json:
              schema: { $ref: '#/components/schemas/HitListEnvelope' }
  /api/elasticapi/v1/annotations/latest/count:
    get:
      tags: [Annotations]
      summary: Count the latest published annotation layers
      operationId: countLatestAnnotations
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
      responses:
        '200':
          description: Count envelope
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CountEnvelope' }
              example:
                success: true
                data: '{"count":1160,"_shards":{"total":1,"successful":1,"skipped":0,"failed":0}}'
                message: ' Latest annotations count retrieved successfully.'
                status: 200
                count: 1160
  /api/elasticapi/v1/annotations/latest/{from}/{size}:
    get:
      tags: [Annotations]
      summary: Page through the latest published annotation layers
      operationId: listLatestAnnotations
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/From'
        - $ref: '#/components/parameters/Size'
      responses:
        '200':
          description: Envelope carrying a page of annotation hits
          content:
            application/json:
              schema: { $ref: '#/components/schemas/HitListEnvelope' }
  /api/elasticapi/v1/annotations/latest/searchMain:
    get:
      tags: [Annotations]
      summary: Search the latest published annotation layers
      operationId: searchLatestAnnotations
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
      responses:
        '200':
          description: Envelope carrying matching annotation hits
          content:
            application/json:
              schema: { $ref: '#/components/schemas/HitListEnvelope' }
  /api/elasticapi/v1/annotations/latest/searchMain/count:
    get:
      tags: [Annotations]
      summary: Count annotation layers matching the main search
      operationId: countSearchLatestAnnotations
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
      responses:
        '200':
          description: Count envelope
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CountEnvelope' }
  /api/elasticapi/v1/annotations/{id}/{index}:
    get:
      tags: [Annotations]
      summary: Retrieve one annotation layer by Elasticsearch id and index
      operationId: getAnnotation
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/Id'
        - $ref: '#/components/parameters/Index'
      responses:
        '200':
          description: Envelope carrying the annotation hit
          content:
            application/json:
              schema: { $ref: '#/components/schemas/HitListEnvelope' }
  /api/elasticapi/v1/annotations/{id}/{index}/documents:
    get:
      tags: [Annotations]
      summary: List the documents carrying one annotation layer
      operationId: getAnnotationDocuments
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/Id'
        - $ref: '#/components/parameters/Index'
      responses:
        '200':
          description: Envelope carrying document hits
          content:
            application/json:
              schema: { $ref: '#/components/schemas/HitListEnvelope' }
components:
  parameters:
    ApiVersion:
      name: Api-Version
      in: header
      required: true
      description: API version selector; the published reference sends `v1` on every call.
      schema:
        type: string
        enum: [v1]
        default: v1
    From:
      name: from
      in: path
      required: true
      description: Zero-based offset of the first hit to return.
      schema: { type: integer, minimum: 0, example: 0 }
    Size:
      name: size
      in: path
      required: true
      description: Number of hits to return.
      schema: { type: integer, minimum: 1, example: 100 }
    Id:
      name: id
      in: path
      required: true
      description: Elasticsearch document id of the record.
      schema: { type: string, example: dGhNsGoB6bp_h9Nar9dI }
    Index:
      name: index
      in: path
      required: true
      description: Elasticsearch index the record lives in.
      schema:
        type: string
        example: corpus_marchenkorpus-version-1-0_1-0_1557736034
  schemas:
    Envelope:
      type: object
      description: Common response envelope returned by every LAUDATIO endpoint.
      properties:
        success: { type: boolean }
        message: { type: string }
        status: { type: integer, example: 200 }
      required: [success]
    HitListEnvelope:
      allOf:
        - $ref: '#/components/schemas/Envelope'
        - type: object
          properties:
            data:
              type: array
              description: Raw Elasticsearch hits.
              items: { $ref: '#/components/schemas/Hit' }
    CountEnvelope:
      allOf:
        - $ref: '#/components/schemas/Envelope'
        - type: object
          properties:
            data:
              type: string
              description: JSON-encoded Elasticsearch count response, returned as a string.
            count:
              type: integer
              description: Number of matching records.
    Hit:
      type: object
      description: >-
        An Elasticsearch hit. `_source` carries the LAUDATIO TEI-ODD derived header
        metadata; its field set differs between corpus, document and annotation indices and
        is not fixed by the API, so it is described as a free-form object rather than
        invented here.
      properties:
        _index: { type: string }
        _type: { type: string }
        _id: { type: string }
        _score: { type: number }
        _source:
          type: object
          additionalProperties: true