Karp Search API v1 — Karps sökgränssnitt

# x-method: searched
# x-source-url: https://spraakbanken4.it.gu.se/karps/v1/openapi.json
# Written by API Evangelist for the api-evangelist/university-of-gothenburg repo on
# 2026-09-01. `x-method` uses the provenance-manifest vocabulary; the artifact's own
# `method:` key uses the enrichment-contract vocabulary. They are not in conflict.
openapi: 3.1.0
info:
  title: Karps sökgränssnitt - API
  description: "Karp search-mode API (Karps sökgränssnitt) — the read-only search surface over the same\
    \ lexical resources. Institution-operated, served from spraakbanken4.it.gu.se. HOSTLESS AS PUBLISHED:\
    \ upstream servers[] is the relative `/karps/v1`; re-based onto the absolute host it was fetched from\
    \ and verified live (GET /karps/v1/config returned HTTP 200, 47,203 bytes, 2026-09-01).\n\n---\n\n\
    UPSTREAM DESCRIPTION\n\n## Karps sökgränssnitt / Karp's search mode\n\nSpråkbanken has many lexical\
    \ resources, listed on our [webpage](https://spraakbanken.gu.se/resurser/lexicon).\n\nKarp's search\
    \ mode makes it possible to search the resources, read the entries, and also to get statistical information.\
    \ For example:\n- What are the different senses of word \\<X\\> in \\<lexicon\\>?\n- How many (and\
    \ which) of the resources have an entry with baseform \"bord\"?\n- What is the frequency distribution\
    \ of part-of-speech tags in \\<lexicon\\>?\n\n## The basics\n\nA **resource** is a collection of **entries**\
    \ with the same fields (or schema). Every entry\nhas a default field - `entryWord` - which is usually\
    \ something like a lemma.\n\n## Sorting the results\n\nAscending and descending sort are available.\
    \ The sorting uses Swedish (POSIX `sv_SE` or MariaDB `utf8mb4_swedish_ci`) collation for text fields.\
    \ It is also possible to \nsort by fields of other types. Sorting is done using the `sort` parameter\
    \ with the following grammar:\n```ebnf\nsort          ::= order | multi_fields ;\norder         ::=\
    \ \"asc\" | \"desc\" ;\nmulti_fields  ::= field_sort ( \",\" field_sort )* ;\nfield_sort    ::= field_name\
    \ \"|\" order ;\n```\n`field_name` is not defined in the grammar, see each API-call for more information\
    \ about available fields.\n\nExamples: `sort=desc`, `sort=entryWord,pos|desc,nativePos|desc`\n\nThe\
    \ default value is `asc`. Only selecting an order uses the default field(s). See the respective search\
    \ commands for defaults.\n\nWhen sorting by multiple fields, the sort will be applied in the given\
    \ order. `asc` is always used when order is emitted."
  version: v1
  x-operator: institution
  x-institution: University of Gothenburg
  x-unit: Språkbanken Text (Department of Swedish, Multilingualism, Language Technology)
  x-provenance:
    generated: '2026-09-01'
    method: searched
    source: https://spraakbanken4.it.gu.se/karps/v1/openapi.json — Fetched 2026-09-01 from the Språkbanken
      Text API documentation index at https://ws.spraakbanken.gu.se/docs/ , which links each service's
      published OpenAPI document. The pristine copy as fetched is in openapi/_original/.
  x-rebased-servers: Upstream servers[] was relative; re-based onto https://spraakbanken4.it.gu.se/karps/v1,
    the absolute host this document was fetched from. Repair, not fabrication — the original is in openapi/_original/.
servers:
- url: https://spraakbanken4.it.gu.se/karps/v1
  description: Production server (re-based from a relative servers[] entry)
paths:
  /config:
    get:
      summary: Get config
      description: 'Returns a description of the contents of each installed resource/lexicon. For example
        the available fields and their types.


        Some resources have `limitedAccess: true` - they will not be searchable without access.


        Some resources have `protectedMetadata: true` - they will not be returned by this call without
        access.'
      operationId: get_config_config_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigResponse'
      security:
      - HTTPBearer: []
      - APIKeyHeader: []
  /search:
    get:
      summary: Search
      description: 'From each provided resource, return the entries that match the query q.


        ### Sorting

        Sorting is supported on fields that are present in all selected resources. The default field is
        `entryWord` (**ascending** order).


        The sort is done within each resource, the results from each resource are not mixed.'
      operationId: do_search_search_get
      security:
      - HTTPBearer: []
      - APIKeyHeader: []
      parameters:
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Query
          description: The query. See https://ws.spraakbanken.gu.se/docs/karp for a description of the
            query language, however, Karp-s does not support sub-queries, exists, missing and freetext.
        description: The query. See https://ws.spraakbanken.gu.se/docs/karp for a description of the query
          language, however, Karp-s does not support sub-queries, exists, missing and freetext.
      - name: size
        in: query
        required: false
        schema:
          type: integer
          default: 10
          title: Size
      - name: from
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: From
      - name: resources
        in: query
        required: true
        schema:
          anyOf:
          - type: string
            minLength: 1
            pattern: ^[^,]+(,[^,]+)*$
          - type: 'null'
          title: Resources
          description: '

            A comma-separated list of resource ID:s, for example `saldo`

            '
        description: '

          A comma-separated list of resource ID:s, for example `saldo`

          '
      - name: sort
        in: query
        required: false
        schema:
          type: string
          description: '

            See [Sorting the results](#section/Sorting-the-results) and API call description for more
            information.

            '
          default: asc
          title: Sort
        description: '

          See [Sorting the results](#section/Sorting-the-results) and API call description for more information.

          '
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResult'
        '500':
          description: Application error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserErrorSchema'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /count:
    get:
      summary: Count
      description: 'From each provided resource, get the entries that match the query q. See http://ws.spraakbanken.gu.se/ws/karp/v7
        for a description of the query language.


        Compile the matching entries on the fields in compile.


        Add additional data requested by using the `columns` parameter.


        ### Sorting


        Sorting is supported for fields that are used in `compile`. The default fields are all the fields
        in `compile`

        (**ascending** order) (they themselves sorted alphabetically, just like the columns).'
      operationId: do_count_count_get
      security:
      - HTTPBearer: []
      - APIKeyHeader: []
      parameters:
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Query
          description: The query. See https://ws.spraakbanken.gu.se/docs/karp for a description of the
            query language, however, Karp-s does not support sub-queries, exists, missing and freetext.
        description: The query. See https://ws.spraakbanken.gu.se/docs/karp for a description of the query
          language, however, Karp-s does not support sub-queries, exists, missing and freetext.
      - name: resources
        in: query
        required: true
        schema:
          anyOf:
          - type: string
            minLength: 1
            pattern: ^[^,]+(,[^,]+)*$
          - type: 'null'
          title: Resources
          description: '

            A comma-separated list of resource ID:s, for example `saldo`

            '
        description: '

          A comma-separated list of resource ID:s, for example `saldo`

          '
      - name: compile
        in: query
        required: true
        schema:
          anyOf:
          - type: string
            minLength: 1
            pattern: ^[^,]+(,[^,]+)*$
          - type: 'null'
          title: Compile on
          description: '

            A list of fields to compile statistics on, for example `baseform`, `pos`, `normalized_form`

            '
        description: '

          A list of fields to compile statistics on, for example `baseform`, `pos`, `normalized_form`

          '
      - name: columns
        in: query
        required: false
        schema:
          type: string
          title: Extra columns
          description: "\nAdd extra data columns to the result. For example: `field1=val_field1,field2=val_field2`\n\
            \nThe left-hand side of `=` denotes  a field that will be used to create columns. Good examples\n\
            are `resourceId` and `ud_pos`. For each unique value in the result, a column will be created\
            \ \nand the field in the right-hand side of `=` \nwill be used for values in the cells of\
            \ that column. If there are multiple values for the right-hand side field they\nwill be shown\
            \ as a list.\n\nIt is possible to replace the field of the right-hand side with the keyword\
            \ `_count` - `columns=resourceId=_count`.\nThis is the default value if `columns` is omitted.\
            \ With this, the number of\nhits per unique value of the selected field will be shown.\n\n\
            The total number of rows and columns from `compile` will always be shown regardless of the\
            \ value of `columns`.\n"
          default: resourceId=_count
        description: "\nAdd extra data columns to the result. For example: `field1=val_field1,field2=val_field2`\n\
          \nThe left-hand side of `=` denotes  a field that will be used to create columns. Good examples\n\
          are `resourceId` and `ud_pos`. For each unique value in the result, a column will be created\
          \ \nand the field in the right-hand side of `=` \nwill be used for values in the cells of that\
          \ column. If there are multiple values for the right-hand side field they\nwill be shown as\
          \ a list.\n\nIt is possible to replace the field of the right-hand side with the keyword `_count`\
          \ - `columns=resourceId=_count`.\nThis is the default value if `columns` is omitted. With this,\
          \ the number of\nhits per unique value of the selected field will be shown.\n\nThe total number\
          \ of rows and columns from `compile` will always be shown regardless of the value of `columns`.\n"
      - name: sort
        in: query
        required: false
        schema:
          type: string
          description: '

            See [Sorting the results](#section/Sorting-the-results) and API call description for more
            information.

            '
          default: asc
          title: Sort
        description: '

          See [Sorting the results](#section/Sorting-the-results) and API call description for more information.

          '
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '500':
          description: Application error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserErrorSchema'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ConfigField:
      properties:
        name:
          type: string
          title: Name
          description: (Machine) name of the field. This name is used by resources to list the available
            fields.
        type:
          type: string
          title: Type
          description: Type of the field, can be text, integer or float or table.
        collection:
          type: boolean
          title: Collection
          description: If `true`, the field is a list of `type`.
          default: false
        label:
          anyOf:
          - $ref: '#/components/schemas/MultiLang'
          - type: 'null'
          description: Label for the field, can be in mulitple languages.
        fields:
          additionalProperties:
            $ref: '#/components/schemas/Field'
          type: object
          title: Fields
          description: If type is table, then there can be sub-fields (that cannot be table).
        categories:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Categories
          description: If set, a list of possible values for this field.
        categoryLabels:
          anyOf:
          - additionalProperties:
              $ref: '#/components/schemas/MultiLang'
            type: object
          - type: 'null'
          title: Categorylabels
          description: For fields with categories, labels for each value (optional, even if categories
            is given).
        protectedMetadata:
          type: boolean
          title: Protectedmetadata
          description: The field is only available for users with access
          default: false
      additionalProperties: false
      type: object
      required:
      - name
      - type
      title: ConfigField
    ConfigResponse:
      properties:
        resources:
          items:
            $ref: '#/components/schemas/ResourceConfig'
          type: array
          title: Resources
          description: All resources available in this instance.
        tags:
          additionalProperties:
            $ref: '#/components/schemas/Tag'
          type: object
          title: Tags
          description: All tags available in this instance. Will be used by some of the resources under
            "resources".
        fields:
          additionalProperties:
            $ref: '#/components/schemas/ConfigField'
          type: object
          title: Fields
          description: All fields available in this instance.
      type: object
      required:
      - resources
      - tags
      - fields
      title: ConfigResponse
    EntryWord:
      properties:
        field:
          type: string
          title: Field
        description:
          $ref: '#/components/schemas/MultiLang'
      type: object
      required:
      - field
      - description
      title: EntryWord
    Field:
      properties:
        name:
          type: string
          title: Name
          description: (Machine) name of the field. This name is used by resources to list the available
            fields.
        type:
          type: string
          title: Type
          description: Type of the field, can be text, integer or float or table.
        collection:
          type: boolean
          title: Collection
          description: If `true`, the field is a list of `type`.
          default: false
        label:
          anyOf:
          - $ref: '#/components/schemas/MultiLang'
          - type: 'null'
          description: Label for the field, can be in mulitple languages.
        fields:
          additionalProperties:
            $ref: '#/components/schemas/Field'
          type: object
          title: Fields
          description: If type is table, then there can be sub-fields (that cannot be table).
        categories:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Categories
          description: If set, a list of possible values for this field.
        categoryLabels:
          anyOf:
          - additionalProperties:
              $ref: '#/components/schemas/MultiLang'
            type: object
          - type: 'null'
          title: Categorylabels
          description: For fields with categories, labels for each value (optional, even if categories
            is given).
        protectedMetadata:
          type: boolean
          title: Protectedmetadata
          description: The field is only available for users with access
          default: false
        resourceId:
          items:
            type: string
          type: array
          title: Resourceid
          description: The resources that this field is available in.
      additionalProperties: false
      type: object
      required:
      - name
      - type
      title: Field
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    HitResponse:
      properties:
        entry:
          additionalProperties: true
          type: object
          title: Entry
        resourceId:
          type: string
          title: Resourceid
      type: object
      required:
      - entry
      - resourceId
      title: HitResponse
    MultiLang:
      anyOf:
      - type: string
      - additionalProperties:
          type: string
        type: object
      title: MultiLang
    ResourceConfig:
      properties:
        resourceId:
          type: string
          title: Resourceid
          description: The resource ID
        fields:
          items:
            $ref: '#/components/schemas/ResourceField'
          type: array
          title: Fields
          description: The fields available in this resource.
        label:
          $ref: '#/components/schemas/MultiLang'
          description: Name for this resource, can be in mulitple languages.
        limitedAccess:
          type: boolean
          title: Limitedaccess
          description: The resource is only available for users with access
          default: false
        protectedMetadata:
          type: boolean
          title: Protectedmetadata
          description: The metadata of the resource is only available for users with access
          default: false
        description:
          anyOf:
          - $ref: '#/components/schemas/MultiLang'
          - type: 'null'
          description: Description of this resource, can be in mulitple languages.
        entryWord:
          $ref: '#/components/schemas/EntryWord'
          description: The default field for this resource.
        updated:
          type: integer
          title: Updated
          description: The timestamp for when this resource was last updated (data or configuration).
            UNIX timestmap in milliseconds.
        size:
          type: integer
          title: Size
          description: The number of entries in this resource.
        link:
          type: string
          title: Link
          description: A link to a relevant page for the resource.
        tags:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Tags
          description: The tags for this resource, see top-level `tags`, for tag labels and description.
      additionalProperties: false
      type: object
      required:
      - resourceId
      - fields
      - label
      - entryWord
      - updated
      - size
      - link
      title: ResourceConfig
    ResourceField:
      properties:
        name:
          type: string
          title: Name
          description: The name of the field. Corresponds to a key under the top-level `fields`.
        primary:
          type: boolean
          title: Primary
          description: 'Fields with `primary: true` are more relevant than fields with `primary: false`.'
      type: object
      required:
      - name
      - primary
      title: ResourceField
    SearchResult:
      properties:
        hits:
          items:
            $ref: '#/components/schemas/HitResponse'
          type: array
          title: Hits
        resourceHits:
          additionalProperties:
            type: integer
          type: object
          title: Resourcehits
        resourceOrder:
          items:
            type: string
          type: array
          title: Resourceorder
        total:
          type: integer
          title: Total
      type: object
      required:
      - hits
      - resourceHits
      - resourceOrder
      - total
      title: SearchResult
    Tag:
      properties:
        label:
          $ref: '#/components/schemas/MultiLang'
        description:
          $ref: '#/components/schemas/MultiLang'
      type: object
      required:
      - label
      - description
      title: Tag
    UserErrorSchema:
      properties:
        message:
          type: string
          title: ''
        code:
          anyOf:
          - type: integer
          - type: 'null'
          title: ''
          description: '### Code definitions


            1: Returned when the database was forced to truncate a value. Query parameter "columns" is
            the issue.


            2: Returned when an unauthenticated user or a user without the proper access tries access
            a restricted resource.


            3: Returned when a JWT was given, but the JWT was malformed or expired.


            4: Returned when an API key was given, but it was malformed, expired or it was not possible
            to verify the key.'
        extra:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: ''
          description: Some errors have data output in addition to the human readable message.
      type: object
      required:
      - message
      title: UserErrorSchema
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-Api-Key