University of Gothenburg Manage Resources API

openapi: 3.2.0
info:
  title: Mink backend Manage Resources 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 Resources
  description: Routes for listing and getting information about all resources, regardless of type.
paths:
  /queue/advance:
    put:
      tags:
      - Manage Resources
      summary: Advance Queue
      description: 'Check the job queue and attempt to advance it.


        For Mink internal use only!


        1. Unqueue jobs that are done, aborted or erroneous

        2. For running jobs, check if process is still running

        3. Run the next job in the queue if there are fewer running jobs than allowed'
      operationId: advance-queue
      parameters:
      - name: secret_key
        in: query
        required: true
        schema:
          type: string
          description: Secret key for authentication
          title: Secret Key
        description: Secret key for authentication
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '401':
          content:
            application/json:
              example:
                status: error
                message: Failed to confirm secret key for protected route
                return_code: invalid_secret_key
          description: Unauthorized
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /queue/health:
    get:
      tags:
      - Manage Resources
      summary: Queue Health
      description: 'Return monitorable queue health statistics for internal checks and for admins.


        ### Example


        ```bash

        curl -X GET ''https://ws.spraakbanken.gu.se/ws/mink/v3/queue/health'' -H ''Authorization: Bearer YOUR_JWT'' -H ''cookie: session_id=MY_SESSION_ID''

        ```'
      operationId: queue-health
      security:
      - OAuth2PasswordBearer: []
      - APIKeyHeader: []
      parameters:
      - name: secret_key
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Secret Key
      - 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/QueueHealthResponse'
        '401':
          content:
            application/json:
              example:
                status: error
                message: Failed to confirm secret key for protected route
                return_code: invalid_secret_key
          description: Unauthorized
        '503':
          content:
            application/json:
              example:
                status: error
                message: Queue health warning detected
                return_code: queue_degraded
                healthy: false
                warning_threshold_seconds: 3600
                warnings:
                - Oldest running job has been active for 7260 seconds
                queue_size: 1
                running_jobs: 1
                waiting_jobs: 0
                max_workers: 1
                last_started: '2026-04-13T07:00:00+02:00'
                seconds_since_last_start: 7260
                oldest_running_started: '2026-04-13T07:00:00+02:00'
                oldest_running_seconds: 7260
                oldest_waiting_seconds: 0
                queue_jobs:
                - resource_id: mink-dxh6e6wtff
                  resource_type: corpus
                  current_process: sparv
                  job_status: running
                  priority: ''
                  queued: '2026-04-13T06:59:55+02:00'
                  started: '2026-04-13T07:00:00+02:00'
                  age_reference: started
                  age_seconds: 7260
              schema:
                $ref: '#/components/schemas/QueueHealthResponse'
          description: Service Unavailable
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /resource/list:
    get:
      tags:
      - Manage Resources
      summary: List Resources
      description: 'List all resources available to the authenticated user, regardless of resource type.


        ### Example


        ```bash

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

        ```'
      operationId: list-resources
      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__core__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
  /resource/status/list:
    get:
      tags:
      - Manage Resources
      summary: List Resource Statuses
      description: 'Return statuses for all resources available to the authenticated user.


        ### Example


        ```bash

        curl -X GET ''https://ws.spraakbanken.gu.se/ws/mink/v3/resource/status/list'' -H ''Authorization: Bearer YOUR_JWT''

        ```'
      operationId: list-resource-statuses
      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/StatusesResponse'
        '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
  /resource/status/get/{resource_id}:
    get:
      tags:
      - Manage Resources
      summary: Get Resource Status
      description: 'Return the status for one resource.


        ### Example


        ```bash

        curl -X GET ''https://ws.spraakbanken.gu.se/ws/mink/v3/resource/status/get/'' -H ''Authorization: Bearer YOUR_JWT''

        ```'
      operationId: get-resource-status
      security:
      - OAuth2PasswordBearer: []
      - APIKeyHeader: []
      parameters:
      - name: resource_id
        in: path
        required: true
        schema:
          type: string
          title: 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/StatusResponse'
        '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 get job for resource
                return_code: failed_getting_job
                info: Error getting job info for resource
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
          description: Internal Server Error
components:
  schemas:
    StatusResponse:
      properties:
        job_status:
          type: string
          title: Job Status
          description: Status of the current job for the resource
          default: ''
        info:
          anyOf:
          - type: string
          - type: 'null'
          title: Info
          description: More detailed information about the response
        resource:
          $ref: '#/components/schemas/ResourceModel'
          description: Object containing information about the resource
          default:
            id: ''
            public_id: ''
            name: {}
            type: ''
            custom_config: false
            source_files: []
        owner:
          $ref: '#/components/schemas/UserModel'
          description: User object containing information about the resource owner
          default:
            id: ''
            name: ''
            email: ''
        job:
          $ref: '#/components/schemas/JobModel'
          description: Job object containing information about the job status
        status:
          type: string
          title: Status
          description: Response status, usually 'success' or 'error'
          default: success
        message:
          type: string
          title: Message
          description: Short message describing the response
          default: ''
        return_code:
          type: string
          title: Return Code
          description: Return code indicating the status of the request, mostly used for frontend error handling
          default: ''
        warnings:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Warnings
          description: List of warnings, if any
      type: object
      description: Model for job status responses.
      examples:
      - status: success
        message: Checked status of job
        return_code: checked_status
        job_status: waiting
        info: Job has been queued
        resource:
          id: mink-vajfgwcqdw
          public_id: mink-vajfgwcqdw
          name:
            swe: Mitt testlexikon
            eng: My test lexicon
          custom_config: true
          source_files:
          - name: test_lexicon_data2.jsonl
            type: unknown
            last_modified: '2026-04-22T12:50:37+02:00'
            size: 62
            path: test_lexicon_data2.jsonl
          sources_deleted: '2026-04-22T12:50:37+02:00'
        job:
          status:
            karp_pipeline: waiting
            karps: none
          current_process: karp_pipeline
          pid: null
          installed_karps: false
          priority: 1
          warnings: ''
          errors: ''
          output: 'Running mink-vajfgwcqdw

            Reading source files: /data/sbdata01/mink-dev-data/lexicon/v/mink-vajfgwcqdw/source/test_lexicon_data2.jsonl

            Using entry schema: {"baseform":{"type":"text","name":"baseform","collection":false,"fields":{},"extra":{"length":4},"categories":[]}}

            Reading source files: /data/sbdata01/mink-dev-data/lexicon/v/mink-vajfgwcqdw/source/test_lexicon_data2.jsonl'
          queued: '2026-06-02T10:25:14+02:00'
          started: ''
          ended: ''
          duration: 0
          progress: 0%
    UserModel:
      properties:
        id:
          type: string
          title: Id
          description: User ID
          default: ''
        name:
          type: string
          title: Name
          description: Name of the user
          default: ''
        email:
          type: string
          title: Email
          description: Email address of the user
          default: ''
        idp:
          anyOf:
          - type: string
          - type: 'null'
          title: Idp
          description: Identity provider of the user
        sub:
          anyOf:
          - type: string
          - type: 'null'
          title: Sub
          description: Subject identifier from the identity provider
      type: object
      description: Model for the user object.
      examples:
      - email: anna.andersson@example.com
        id: example-idp-abc123
        idp: example-idp
        name: Anna Andersson
        sub: abc123
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
    ErrorResponse401:
      properties:
        status:
          type: string
          title: Status
          description: Response status, usually 'success' or 'error'
          default: error
        message:
          type: string
          title: Message
          description: Short message describing the response
          default: ''
        return_code:
          type: string
          title: Return Code
          description: Return code indicating the status of the request, mostly used for frontend error handling
          default: ''
        info:
          anyOf:
          - type: string
          - type: 'null'
          title: Info
          description: Additional information about the error
        warnings:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Warnings
          description: List of warnings, if any
      type: object
      description: Model for 401 error responses.
      examples:
      - message: Failed to authenticate
        return_code: failed_authenticating
        status: error
      - message: The provided JWT has expired
        return_code: jwt_expired
        status: error
      - message: API key not recognized
        return_code: apikey_not_found
        status: error
      - message: API key expired
        return_code: apikey_expired
        status: error
      - message: No login credentials provided
        return_code: missing_login_credentials
        status: error
      - message: Mink admin status could not be confirmed
        return_code: not_admin
        status: error
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
    mink__core__models__ListResourcesResponse:
      properties:
        status:
          type: string
          title: Status
          description: Response status, usually 'success' or 'error'
          default: success
        message:
          type: string
          title: Message
          description: Short message describing the response
          default: ''
        return_code:
          type: string
          title: Return Code
          description: Return code indicating the status of the request, mostly used for frontend error handling
          default: ''
        info:
          anyOf:
          - type: string
          - type: 'null'
          title: Info
          description: More detailed information about the response
        warnings:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Warnings
          description: List of warnings, if any
        resources:
          items:
            type: string
          type: array
          title: Resources
          description: List of resource IDs
          default: []
      type: object
      description: Model for responses listing resource IDs.
      examples:
      - info: Listing available resources
        message: Listing contents
        resources:
        - mink-dxh6e6wtff
        - mink-j86tfreaf9
        - mink-3qbh7tra6g
        return_code: listing_content
        status: success
    StatusesResponse:
      properties:
        status:
          type: string
          title: Status
          description: Response status, usually 'success' or 'error'
          default: success
        message:
          type: string
          title: Message
          description: Short message describing the response
          default: ''
        return_code:
          type: string
          title: Return Code
          description: Return code indicating the status of the request, mostly used for frontend error handling
          default: ''
        info:
          anyOf:
          - type: string
          - type: 'null'
          title: Info
          description: More detailed information about the response
        warnings:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Warnings
          description: List of warnings, if any
        resources:
          items:
            $ref: '#/components/schemas/JobStatusModel'
          type: array
          title: Resources
          description: List of resource objects containing information about the corpus
          default: []
      type: object
      description: Model for multiple job statuses responses.
      examples:
      - status: success
        message: Listing contents
        return_code: listing_content
        info: Listing resource infos
        resources:
        - job_status: done
          info: Job was completed successfully
          resource:
            id: mink-vajfgwcqdw
            public_id: mink-vajfgwcqdw
            name:
              swe: Mitt testlexikon
              eng: My test lexicon
            custom_config: true
            source_files:
            - name: test_lexicon_data2.jsonl
              type: unknown
              last_modified: '2026-04-22T12:50:37+02:00'
              size: 62
              path: test_lexicon_data2.jsonl
            sources_deleted: '2026-04-22T12:50:37+02:00'
          job:
            status:
              karp_pipeline: waiting
              karps: none
            current_process: karp_pipeline
            pid: null
            installed_karps: false
            priority: 1
            warnings: ''
            errors: ''
            output: 'Running mink-vajfgwcqdw

              Reading source files: /data/sbdata01/mink-dev-data/lexicon/v/mink-vajfgwcqdw/source/test_lexicon_data2.jsonl

              Using entry schema: {"baseform":{"type":"text","name":"baseform","collection":false,"fields":{},"extra":{"length":4},"categories":[]}}

              Reading source files: /data/sbdata01/mink-dev-data/lexicon/v/mink-vajfgwcqdw/source/test_lexicon_data2.jsonl'
            queued: '2026-06-02T10:25:14+02:00'
            started: ''
            ended: ''
            duration: 0
            progress: 0%
    JobStatusModel:
      properties:
        job_status:
          type: string
          title: Job Status
          description: Status of the current job for the resource
          default: ''
        info:
          type: string
          title: Info
          description: Info about the job status
          default: ''
        resource:
          $ref: '#/components/schemas/ResourceModel'
          description: Object containing information about the resource
          default:
            id: ''
            public_id: ''
            name: {}
            type: ''
            custom_config: false
            source_files: []
        owner:
          $ref: '#/components/schemas/UserModel'
          description: User object containing information about the resource owner
          default:
            id: ''
            name: ''
            email: ''
        job:
          $ref: '#/components/schemas/JobModel'
          description: Job object containing information about the job status
      type: object
      description: Model for the status of a resource (used as base for StatusResponse and StatusesResponse).
      examples:
      - info: Job has been queued
        resource:
          id: mink-vajfgwcqdw
          public_id: mink-vajfgwcqdw
          name:
            swe: Mitt testlexikon
            eng: My test lexicon
          custom_config: true
          source_files:
          - name: test_lexicon_data2.jsonl
            type: unknown
            last_modified: '2026-04-22T12:50:37+02:00'
            size: 62
            path: test_lexicon_data2.jsonl
          sources_deleted: '2026-04-22T12:50:37+02:00'
        owner:
          id: example-idp-abc123
          name: Anna Andersson
          email: anna.andersson@example.com
          idp: example-idp
          sub: abc123
        job:
          status:
            karp_pipeline: waiting
            karps: none
          current_process: karp_pipeline
          pid: null
          installed_karps: false
          priority: 1
          warnings: ''
          errors: ''
          output: 'Running mink-vajfgwcqdw

            Reading source files: /data/sbdata01/mink-dev-data/lexicon/v/mink-vajfgwcqdw/source/test_lexicon_data2.jsonl

            Using entry schema: {"baseform":{"type":"text","name":"baseform","collection":false,"fields":{},"extra":{"length":4},"categories":[]}}

            Reading source files: /data/sbdata01/mink-dev-data/lexicon/v/mink-vajfgwcqdw/source/test_lexicon_data2.jsonl'
          queued: '2026-06-02T10:25:14+02:00'
          started: ''
          ended: ''
          duration: 0
          progress: 0%
    BaseResponse:
      properties:
        status:
          type: string
          title: Status
          description: Response status, usually 'success' or 'error'
          default: success
        message:
          type: string
          title: Message
          description: Short message describing the response
          default: ''
        return_code:
          type: string
          title: Return Code
          description: Return code indicating the status of the request, mostly used for frontend error handling
          default: ''
        info:
          anyOf:
          - type: string
          - type: 'null'
          title: Info
          description: More detailed information about the response
        warnings:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Warnings
          description: List of warnings, if any
      type: object
      description: Base response model with common fields.
    ResourceModel:
      properties:
        id:
          type: string
          title: Id
          description: Mink resource ID
          default: ''
        public_id:
          type: string
          title: Public Id
          description: Public resource ID
          default: ''
        name:
          additionalProperties:
            type: string
          type: object
          title: Name
          description: Name of the resource in different languages
          default: {}
        type:
          type: string
          title: Type
          description: Type of the resource (e.g., 'corpus', 'metadata')
          default: ''
        custom_config:
          type: boolean
          title: Custom Config
          description: Whether the current resource config was uploaded as a custom config
          default: false
        source_files:
          items:
            $ref: '#/components/schemas/FileModel'
          type: array
          title: Source Files
          description: List of source files associated with the resource
          default: []
      type: object
      description: Model for the resource object.
      examples:
      - custom_config: false
        id: mink-dxh6e6wtff
        name:
          eng: ''
          swe: Min testkorpus
        public_id: mink-dxh6e6wtff
        source_files:
        - last_modified: '2022-06-10T17:05:18+02:00'
          name: dokument1.xml
          path: dokument1.xml
          size: 1397
          type: application/xml
        - last_modified: '2022-06-10T17:05:16+02:00'
          name: dokument2.xml
          path: dokument2.xml
          size: 116
          type: application/xml
        type: corpus
    ErrorResponse400:
      properties:
        status:
          type: string
          title: Status
          description: Response status, usually 'success' or 'error'
          default: error
        message:
          type: string
          title: Message
          description: Short message describing the response
          default: ''
        return_code:
          type: string
          title: Return Code
          description: Return code indicating the status of the request, mostly used for frontend error handling
          default: ''
        info:
          anyOf:
          - type: string
          - type: 'null'
          title: Info
          description: Additional information about the error
        warnings:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Warnings
          description: List of warnings, if any
      type: object
      description: Model for 400 error responses.
      examples:
      - message: No resource ID provided
        return_code: missing_resource_id
        status: error
    ErrorResponse404Resource:
      properties:
        status:
          type: string
          title: Status
          description: Response status, usually 'success' or 'error'
          default: error
        message:
          type: string
          title: Message
          description: Short message describing the response
          default: ''
        return_code:
          type: string
          title: Return Code
          description: Return code indicating the status of the request, mostly used for frontend error handling
          default: ''
        info:
          anyOf:
          - type: string
          - type: 'null'
          title: Info
          description: Additional information about the error
        warnings:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Warnings
          description: List of warnings, if any
      type: object
      description: Model for 404 resource not found error responses.
      examples:
      - message: Resource does not exist or you do not have access to it
        return_code: resource_not_found
        status: error
    FileModel:
      properties:
        name:
          type: string
          title: Name
          description: Name of the file
          default: ''
        type:
          type: string
          title: Type
          description: MIME type of the file
          default: ''
        last_modified:
          type: string
          title: Last Modified
          description: Last modified date of the file
          default: ''
        size:
          type: integer
          title: Size
          description: Size of the file in bytes
          default: 0
        path:
          type: string
          title: Path
          description: Path to the file in the storage system
          default: ''
      type: object
      description: Model for file list.
      examples:
      - last_modified: '2022-06-10T17:05:18+02:00'
        name: dokument1.xml
        path: dokument1.xml
        size: 1397
        type: application/xml
      - last_modified: '2022-06-10T17:05:16+02:00'
        name: dokument2.xml
        path: dokument2.xml
        size: 116
        type: application/xml
    QueueHealthJobModel:
      properties:
        resource_id:
          type: string
          title: Resource Id
          description: Mink resource ID
          default: ''
        resource_type:
          type: string
          title: Resource Type
          description: Resource type
          default: ''
        current_process:
          anyOf:
          - type: string
          - type: 'null'
          title: Current Process
          description: Current queue process
        job_status:
          type: string
          title: Job Status
          description: Current status for the queue process
          default: none
        priority:
          anyOf:
          - type: integer
          - type: string
          title: Priority
          description: Queue priority
          default: ''
        queued:
          type: string
          title: Queued
          description: Timestamp of when the job was queued
          default: ''
        started:
          type: string
          title: Started
          description: Timestamp of when the current process started
          default: ''
        age_reference:
          type: string
          title: Age Reference
          description: Whether age_seconds is measured from queued or started
          default: queued
        age_seconds:
          type: integer
          title: Age Seconds
          description: Seconds since the age_reference timestamp
          default: 0
      type: object
      description: Model for one active queue entry.
    ErrorResponse500:
      properties:
        status:
          type: string
          title: Status
          description: Response status, usually 'success' or 'error'
          default: error
        message:
          type: string
          title: Message
          description: Short message describing the response
          default: ''
        return_code:
          type: string
          title: Return Code
          description: Return code indicating the s

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