University of Gothenburg Manage Lexicons API

openapi: 3.2.0
info:
  title: Mink backend Manage Lexicons API
  description: '## Introduction


    The Mink backend is a REST API that powers the Mink frontend, Språkbanken''s data

    platform.'
  x-logo:
    url: https://raw.githubusercontent.com/spraakbanken/mink-backend/main/mink/static/mink.svg
  contact:
    name: Språkbanken
    url: https://spraakbanken.gu.se/
    email: sb-info@svenska.gu.se
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  version: 3.1.0.dev
servers:
- url: https://ws.spraakbanken.gu.se/ws/mink/v3
  description: Production server
- url: https://ws.spraakbanken.gu.se/ws/mink/dev
  description: Development server
tags:
- name: Manage Lexicons
  description: Routes for managing lexicon resources with Karp.
paths:
  /lexicon/create:
    post:
      tags:
      - Manage Lexicons
      summary: Create Lexicon
      description: 'Create a new lexicon.


        ### Example


        ```bash

        curl -X POST ''https://ws.spraakbanken.gu.se/ws/mink/v3/lexicon/create'' -H ''Authorization: Bearer YOUR_JWT''

        ```'
      operationId: create-lexicon
      security:
      - OAuth2PasswordBearer: []
      - APIKeyHeader: []
      parameters:
      - name: session_id
        in: cookie
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Session ID
          title: Session Id
        description: Session ID
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateResourceResponse'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse401'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404Resource'
          description: Not Found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse422'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              example:
                status: error
                message: Failed to create resource
                return_code: failed_creating_resource
                info: BaseException
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
          description: Internal Server Error
  /lexicon/list:
    get:
      tags:
      - Manage Lexicons
      summary: List Lexicons
      description: 'List the IDs of all available lexicons.


        ### Example


        ```bash

        curl ''https://ws.spraakbanken.gu.se/ws/mink/v3/lexicon/list'' -H ''Authorization: Bearer YOUR_JWT''

        ```'
      operationId: list-lexicons
      security:
      - OAuth2PasswordBearer: []
      - APIKeyHeader: []
      parameters:
      - name: session_id
        in: cookie
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Session ID
          title: Session Id
        description: Session ID
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mink__karp__models__ListResourcesResponse'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse401'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404Resource'
          description: Not Found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse422'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
          description: Internal Server Error
  /lexicon/remove/{resource_id}:
    delete:
      tags:
      - Manage Lexicons
      summary: Remove Lexicon
      description: 'Remove a lexicon from the storage server.


        Will attempt to abort any running job for this lexicon and also remove it from the Karp server.


        ### Example


        ```bash

        curl -X DELETE ''https://ws.spraakbanken.gu.se/ws/mink/v3/lexicon/remove/'' -H ''Authorization: Bearer YOUR_JWT''

        ```'
      operationId: remove-lexicon
      security:
      - OAuth2PasswordBearer: []
      - APIKeyHeader: []
      parameters:
      - name: resource_id
        in: path
        required: true
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Resource ID
          title: Resource Id
        description: Resource ID
      - name: session_id
        in: cookie
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Session ID
          title: Session Id
        description: Session ID
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
              example:
                status: success
                message: Resource successfully removed
                return_code: removed_resource
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse401'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404Resource'
          description: Not Found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse422'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              example:
                status: error
                message: Failed to remove content
                return_code: failed_removing_content
                info: Failed to remove resource from Karp's search mode
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
          description: Internal Server Error
  /lexicon/sources/upload/{resource_id}:
    put:
      tags:
      - Manage Lexicons
      summary: Upload Sources
      description: 'Upload the attached files as source files.


        Attached files will be added to the resource or replace existing ones. Files identical in name, size and md5

        checksum will not be uploaded again.


        ### Example


        ```bash

        curl -X PUT ''https://ws.spraakbanken.gu.se/ws/mink/v3/lexicon/sources/upload/'' -H ''Authorization: Bearer YOUR_JWT'' -F ''files=@path_to_file''

        ```'
      operationId: upload-lexicon-sources
      security:
      - OAuth2PasswordBearer: []
      - APIKeyHeader: []
      parameters:
      - name: resource_id
        in: path
        required: true
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Resource ID
          title: Resource Id
        description: Resource ID
      - name: session_id
        in: cookie
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Session ID
          title: Session Id
        description: Session ID
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_upload-lexicon-sources'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '201':
          content:
            application/json:
              example:
                status: success
                message: File(s) successfully uploaded
                return_code: uploaded_file
                warnings:
                - File 'example.jsonl' already existed and was replaced during upload.
          description: Created
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse401'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404Resource'
          description: Not Found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse422'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              example:
                status: error
                message: Failed to upload file(s)
                return_code: failed_uploading_file
                info: BaseException
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
          description: Internal Server Error
        '413':
          content:
            application/json:
              example:
                status: error
                message: Request data too large
                return_code: content_too_large
                file: example.txt
                info: max file size exceeded
                max_size_mb: 10
              schema:
                $ref: '#/components/schemas/ErrorResponse413'
          description: Request Entity Too Large
  /lexicon/sources/list/{resource_id}:
    get:
      tags:
      - Manage Lexicons
      summary: List Sources
      description: 'List the available source files.


        ### Example


        ```bash

        curl ''https://ws.spraakbanken.gu.se/ws/mink/v3/lexicon/sources/list/'' -H ''Authorization: Bearer YOUR_JWT''

        ```'
      operationId: list-lexicon-sources
      security:
      - OAuth2PasswordBearer: []
      - APIKeyHeader: []
      parameters:
      - name: resource_id
        in: path
        required: true
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Resource ID
          title: Resource Id
        description: Resource ID
      - name: session_id
        in: cookie
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Session ID
          title: Session Id
        description: Session ID
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListingFilesResponse'
              example:
                status: success
                message: Listing contents
                return_code: listing_content
                info: Listing source files
                contents:
                - name: dokument1.xml
                  type: application/xml
                  last_modified: '2022-06-10T17:05:18+02:00'
                  size: 1397
                  path: dokument1.xml
                - name: dokument2.xml
                  type: application/xml
                  last_modified: '2022-06-10T17:05:16+02:00'
                  size: 116
                  path: dokument2.xml
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse401'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404Resource'
          description: Not Found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse422'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              example:
                status: error
                message: Failed to list contents
                return_code: failed_listing_content
                info: Failed to list source files
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
          description: Internal Server Error
  /lexicon/sources/remove/{resource_id}:
    delete:
      tags:
      - Manage Lexicons
      summary: Remove Sources
      description: 'Remove the source file given in the `remove` parameter from the resource.


        The file is provided as path relative to the source directory.


        ### Example


        ```bash

        curl -X DELETE ''https://ws.spraakbanken.gu.se/ws/mink/v3/lexicon/sources/remove/?remove='' -H ''Authorization: Bearer YOUR_JWT''

        ```'
      operationId: remove-lexicon-sources
      security:
      - OAuth2PasswordBearer: []
      - APIKeyHeader: []
      parameters:
      - name: resource_id
        in: path
        required: true
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Resource ID
          title: Resource Id
        description: Resource ID
      - name: remove
        in: query
        required: true
        schema:
          type: string
          description: File to remove, given as path relative to the source directory
          title: Remove
        description: File to remove, given as path relative to the source directory
      - name: session_id
        in: cookie
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Session ID
          title: Session Id
        description: Session ID
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
              example:
                status: success
                message: Content successfully removed
                return_code: removed_content
                info: Removed source files
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse401'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404Resource'
          description: Not Found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse422'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              example:
                status: error
                message: Failed to remove content
                return_code: failed_removing_content
                info: Failed to remove some source files
                failed:
                - file1.xml
                - file2.xml
                succeeded:
                - file3.xml
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
          description: Internal Server Error
  /lexicon/sources/download/{resource_id}:
    get:
      tags:
      - Manage Lexicons
      summary: Download Sources
      description: 'Download the source file.


        Download as zip if the `zip` query parameter is set to `true`.


        ### Example


        ```bash

        curl ''https://ws.spraakbanken.gu.se/ws/mink/v3/lexicon/sources/download/&zip=true'' -H ''Authorization: Bearer YOUR_JWT''

        ```'
      operationId: download-lexicon-sources
      security:
      - OAuth2PasswordBearer: []
      - APIKeyHeader: []
      parameters:
      - name: resource_id
        in: path
        required: true
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Resource ID
          title: Resource Id
        description: Resource ID
      - name: zip
        in: query
        required: false
        schema:
          type: boolean
          description: Whether to zip the file or not
          default: false
          title: Zip
        description: Whether to zip the file or not
      - name: session_id
        in: cookie
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Session ID
          title: Session Id
        description: Session ID
      responses:
        '200':
          description: A file download response
          content:
            application/octet-stream: {}
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse401'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404File'
          description: Not Found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse422'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              example:
                status: error
                message: Failed to download file(s)
                return_code: failed_downloading_file
                info: BaseException
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
          description: Internal Server Error
  /lexicon/config/upload/{resource_id}:
    put:
      tags:
      - Manage Lexicons
      summary: Upload Config
      description: 'Upload a lexicon configuration as file or plain text (using the `config` parameter).


        The config must be in yaml format. If a config file already exists for the given resource it will be replaced by the

        newly uploaded one.


        Please note that any yaml comments may be removed from your config upon upload.


        ### Example


        ```bash

        curl -X PUT ''https://ws.spraakbanken.gu.se/ws/mink/v3/lexicon/config/upload/'' -H ''Authorization: Bearer YOUR_JWT'' -F ''file=@path_to_config_file''

        ```'
      operationId: upload-lexicon-config
      security:
      - OAuth2PasswordBearer: []
      - APIKeyHeader: []
      parameters:
      - name: resource_id
        in: path
        required: true
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Resource ID
          title: Resource Id
        description: Resource ID
      - name: config
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: The config file as plain text
          title: Config
        description: The config file as plain text
      - name: custom-config
        in: query
        required: false
        schema:
          type: boolean
          description: Whether this upload should be marked as a custom config upload
          default: true
          title: Custom-Config
        description: Whether this upload should be marked as a custom config upload
      - name: session_id
        in: cookie
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Session ID
          title: Session Id
        description: Session ID
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_upload-lexicon-config'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
              example:
                status: success
                message: File(s) successfully uploaded
                return_code: uploaded_file
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse401'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404Resource'
          description: Not Found
        '422':
          content:
            application/json:
              example:
                status: error
                message: Validation Error
                return_code: validation_error
                info: Both a file and plain text config were provided
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              example:
                status: error
                message: Failed to upload file(s)
                return_code: failed_uploading_file
                info: BaseException
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
          description: Internal Server Error
  /lexicon/config/download/{resource_id}:
    get:
      tags:
      - Manage Lexicons
      summary: Download Config
      description: 'Download the lexicon config file in YAML format.


        ### Example


        ```bash

        curl ''https://ws.spraakbanken.gu.se/ws/mink/v3/lexicon/config/download/'' -H ''Authorization: Bearer YOUR_JWT''

        ```'
      operationId: download-lexicon-config
      security:
      - OAuth2PasswordBearer: []
      - APIKeyHeader: []
      parameters:
      - name: resource_id
        in: path
        required: true
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Resource ID
          title: Resource Id
        description: Resource ID
      - name: session_id
        in: cookie
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Session ID
          title: Session Id
        description: Session ID
      responses:
        '200':
          description: A file download response
          content:
            application/octet-stream: {}
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse401'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404File'
          description: Not Found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse422'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              example:
                status: error
                message: Failed to download file(s)
                return_code: failed_downloading_file
                info: BaseException
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
          description: Internal Server Error
  /lexicon/exports/list/{resource_id}:
    get:
      tags:
      - Manage Lexicons
      summary: List Exports
      description: 'List the available export files created by Karp pipeline.


        ### Example


        ```bash

        curl ''https://ws.spraakbanken.gu.se/ws/mink/v3/lexicon/exports/list/'' -H ''Authorization: Bearer YOUR_JWT''

        ```'
      operationId: list-lexicon-exports
      security:
      - OAuth2PasswordBearer: []
      - APIKeyHeader: []
      parameters:
      - name: resource_id
        in: path
        required: true
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Resource ID
          title: Resource Id
        description: Resource ID
      - name: session_id
        in: cookie
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Session ID
          title: Session Id
        description: Session ID
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListingFilesResponse'
              example:
                status: success
                message: Listing contents
                return_code: listing_content
                info: Listing export files
                contents:
                - name: dokument1.csv
                  type: text/csv
                  last_modified: '2022-06-10T17:55:37+02:00'
                  size: 4876
                  path: csv_export/dokument1.csv
                - name: dokument1_export.xml
                  type: application/xml
                  last_modified: '2022-06-10T17:55:38+02:00'
                  size: 13429
                  path: xml_export.pretty/dokument1_export.xml
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse401'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404Resource'
          description: Not Found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse422'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              example:
                status: error
                message: Failed to list contents
                return_code: failed_listing_content
                info: Failed to list export files
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
          description: Internal Server Error
  /lexicon/exports/download/{resource_id}:
    get:
      tags:
      - Manage Lexicons
      summary: Download Exports
      description: 'Download all available export files created by the Karp pipeline.


        The parameters `file` and `dir` may be used to download a specific export file or a directory of export files. These

        parameters must be supplied as paths relative to the export directory. Only one of these parameters may be applied

        at a time.


        The `zip` parameter may be set to `false` in combination with the `file` param to avoid zipping the file to be

        downloaded. If `zip` is used without the file parameter it will have no effect.


        ### Example


        ```bash

        curl ''https://ws.spraakbanken.gu.se/ws/mink/v3/lexicon/exports/download/?file=some_file_name&zip=true'' -H ''Authorization: Bearer YOUR_JWT''

        ```'
      operationId: download-lexicon-exports
      security:
      - OAuth2PasswordBearer: []
      - APIKeyHeader: []
      parameters:
      - name: resource_id
        in: path
        required: true
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Resource ID
          title: Resource Id
        description: Resource ID
      - name: file
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: The file name or path to download
          title: File
        description: The file name or path to download
      - name: dir
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: The directory to download
          title: Dir
        description: The directory to download
      - name: zip
        in: query
        required: false
        schema:
          type: boolean
          description: Whether to zip the file or not
          default: true
          title: Zip
        description: Whether to zip the file or not
      - name: session_id
        in: cookie
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Session ID
          title: Session Id
        description: Session ID
      responses:
        '200':
          description: A file download response
          content:
            application/octet-stream: {}
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse401'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404File'
          description: Not Found
        '422':
          content:
            application/json:
              example:
                status: error
                message: Validation Error
                return_code: validation_error
                info: Both 'file' and 'dir' parameters were provided
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              example:
                status: error
                message: Failed to download file(s)
                return_code: failed_downloading_file
                info: BaseException
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
          description: Internal Server Error
  /lexicon/exports/remove/{resource_id}:
    delete:
      tags:
      - Manage Lexicons
      summary: Remove Exports
      description: 'Remove all output files for the resource from the Karp pipeline server.


        This action cannot be performed while a job is running.


        ### Example


        ```bash

        curl -X DELETE ''https://ws.spraakbanken.gu.se/ws/mink/v3/lexicon/exports/remove/'' -H ''Authorization: Bearer YOUR_JWT''

        ```'
      operationId: remove-lexicon-exports
      security:
      - OAuth2PasswordBearer: []
      - APIK

# --- truncated at 32 KB (70 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/university-of-gothenburg/refs/heads/main/openapi/university-of-gothenburg-manage-lexicons-api-openapi.yml