University of Helsinki Documents API

openapi: 3.2.0
info:
  title: Laji Documents API
  description: '## Authentication


    This API requires an **Access Token**.'
  version: '1'
  contact: {}
servers:
- url: https://api.laji.fi
tags:
- name: Documents
paths:
  /documents/batch:
    post:
      operationId: DocumentsController_startBatchJob
      parameters:
      - name: Person-Token
        required: false
        description: Person's authentication token. It is required.
        in: header
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/store-document'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchJobValidationStatusResponse'
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '401':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '403':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '406':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '422':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '500':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
      security:
      - Access token: []
      - Lang: []
      - Person token: []
      summary: Starts a batch job that validates the documents.
      tags:
      - Documents
  /documents/batch/{jobID}:
    get:
      operationId: DocumentsController_getBatchJobStatus
      parameters:
      - name: jobID
        required: true
        in: path
        schema:
          type: string
      - name: Person-Token
        required: false
        description: Person's authentication token. It is required.
        in: header
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchJobValidationStatusResponse'
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '401':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '403':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '406':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '422':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '500':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
      security:
      - Access token: []
      - Lang: []
      - Person token: []
      summary: Get a batch job's status.
      tags:
      - Documents
    post:
      operationId: DocumentsController_completeBatchJob
      parameters:
      - name: jobID
        required: true
        in: path
        schema:
          type: string
      - name: publicityRestrictions
        required: false
        in: query
        schema:
          type: string
          enum:
          - MZ.publicityRestrictionsPublic
          - MZ.publicityRestrictionsProtected
          - MZ.publicityRestrictionsPrivate
      - name: dataOrigin
        required: false
        in: query
        schema:
          type: string
          enum:
          - MY.dataOriginPaperForm
          - MY.dataOriginWebForm
          - MY.dataOriginSpreadsheetFile
      - name: Person-Token
        required: false
        description: Person's authentication token. It is required.
        in: header
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchJobValidationStatusResponse'
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '401':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '403':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '406':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '422':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '500':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
      security:
      - Access token: []
      - Lang: []
      - Person token: []
      summary: Completes a given batch job by sending them to the store/warehouse.
      tags:
      - Documents
  /documents/validate:
    post:
      operationId: DocumentsController_validate
      parameters:
      - name: informalTaxonGroup
        required: false
        in: query
        description: 'Taxon belongs to informal taxon group only: Validate that taxon belongs to informal taxon group(s). Multiple values are separated by a comma (,).'
        schema:
          type: string
      - name: field
        required: false
        in: query
        description: JSON pointer to the field being validated (defaults to the whole document).
        schema:
          type: string
      - name: validator
        required: false
        in: query
        description: Name of the validator to run (default all specified in the form).
        schema:
          type: string
          enum:
          - noExistingGatheringsInNamedPlace
          - wbcNamedPlaceExists
          - uniqueNamedPlaceAlternativeIDs
          - namedPlaceNotTooNearOtherPlaces
          - waterbirdPairCount
          - taxonBelongsToInformalTaxonGroup
      - name: type
        required: false
        in: query
        description: Run validators of this type
        schema:
          default: error
          type: string
          enum:
          - error
          - warning
      - name: Person-Token
        required: false
        description: Person's authentication token. It is required.
        in: header
        schema:
          type: string
      responses:
        '204':
          description: Validation raised no errors
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '401':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '403':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '406':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '422':
          description: Validation raised errors
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                  properties:
                    errorCode:
                      enum:
                      - VALIDATION_EXCEPTION
                    details:
                      type: object
                      additionalProperties:
                        type: array
                        items:
                          type: string
                - type: object
                  properties:
                    errorCode:
                      type: string
                    message:
                      type: string
              example:
                errorCode: VALIDATION_EXCEPTION
                details:
                  /json/pointer/to/field:
                  - error message
                  - another error message
        '500':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
      security:
      - Access token: []
      - Lang: []
      - Person token: []
      summary: Validate a document
      tags:
      - Documents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/store-document'
  /documents/count/byYear:
    get:
      operationId: DocumentsController_getCountByYear
      parameters:
      - name: collectionID
        required: false
        in: query
        description: Limit the list of documents to a certain collection
        schema:
          type: string
      - name: formID
        required: false
        in: query
        description: Limit the list of documents to a certain form
        schema:
          type: string
      - name: namedPlace
        required: false
        in: query
        description: Limit the list of documents to a certain named place
        schema:
          type: string
      - name: Person-Token
        required: false
        description: Person's authentication token. It is required.
        in: header
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DocumentCountItemResponse'
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '401':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '403':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '406':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '422':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '500':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
      security:
      - Access token: []
      - Lang: []
      - Person token: []
      summary: Get count of documents by type (currently just "byYear")
      tags:
      - Documents
  /documents/stats:
    get:
      operationId: DocumentsController_getStatistics
      parameters:
      - name: namedPlace
        required: true
        in: query
        description: Limit the list of documents to a certain named place
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatisticsResponse'
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '401':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '403':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '406':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '422':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '500':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
      security:
      - Access token: []
      - Lang: []
      - Person token: []
      summary: Get the median date of documents for a named place
      tags:
      - Documents
  /documents:
    get:
      operationId: DocumentsController_getPage
      parameters:
      - name: page
        required: false
        in: query
        schema:
          default: 1
          type: integer
      - name: pageSize
        required: false
        in: query
        schema:
          default: 20
          type: integer
      - name: namedPlace
        required: false
        in: query
        description: Limit the list of documents to a certain named place
        schema:
          type: string
      - name: selectedFields
        required: false
        in: query
        description: Comma separated list of field names to include in the response
        schema:
          type: string
      - name: observationYear
        required: false
        in: query
        description: Limit the list of documents to a certain observation year
        schema:
          type: number
      - name: templates
        required: false
        in: query
        schema:
          default: false
          type: boolean
      - name: collectionID
        required: false
        in: query
        description: Collection id. Child collections are also fetched.
        schema:
          type: string
      - name: sourceID
        required: false
        in: query
        description: Limit the list of documents to a certain source application.
        schema:
          type: string
      - name: formID
        required: false
        in: query
        description: Use this form's features for the request.
        schema:
          type: string
      - name: selfAsEditorOrCreator
        required: false
        in: query
        description: Some collections return all users documents. This makes the result include only documents that the user is owner or editor of.
        schema:
          default: false
          type: boolean
      - name: Person-Token
        required: false
        description: Person's authentication token. It is required.
        in: header
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  currentPage:
                    type: integer
                  pageSize:
                    type: integer
                  total:
                    type: integer
                  lastPage:
                    type: integer
                  prevPage:
                    type: integer
                  nextPage:
                    type: integer
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/store-document'
                required:
                - currentPage
                - pageSize
                - total
                - lastPage
                - results
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '401':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '403':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '406':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '422':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '500':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
      security:
      - Access token: []
      - Lang: []
      - Person token: []
      summary: Get a page of documents
      tags:
      - Documents
    post:
      operationId: DocumentsController_create
      parameters:
      - name: Person-Token
        required: false
        description: Person's authentication token
        in: header
        schema:
          type: string
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/store-document'
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '401':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '403':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '406':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '422':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '500':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
      security:
      - Access token: []
      - Lang: []
      - Person token: []
      summary: Create a new document
      tags:
      - Documents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/store-document'
  /documents/{id}:
    get:
      operationId: DocumentsController_get
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: Person-Token
        required: false
        description: Person's authentication token. It is required.
        in: header
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/store-document'
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '401':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '403':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '406':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '422':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
        '500':
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                  localized:
                    type: boolean
      security:
      - Access token: []
      - Lang: []
      - Person token: []
      summary: Get a document
      tags:
      - Documents
    put:
      operationId: DocumentsController_update
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: s

# --- truncated at 32 KB (210 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/university-of-helsinki/refs/heads/main/openapi/university-of-helsinki-documents-api-openapi.yml