Språkbanken Text Metadata API v3

# x-method: searched
# x-source-url: https://ws.spraakbanken.gu.se/ws/metadata/v3/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: Språkbanken Text Metadata API
  description: 'The Språkbanken Text Metadata API is the catalogue over everything else — corpora, lexicons,
    models, analyses, utilities and collections — with BibTeX citation export and a published JSON schema
    endpoint. Institution-operated and self-describing: the OpenAPI document is served by the API itself
    at /ws/metadata/v3/openapi.json on a University of Gothenburg host. Verified live 2026-09-01: GET
    /ws/metadata/v3/ returned HTTP 200 with 2,531,491 bytes of catalogue JSON.


    ---


    UPSTREAM DESCRIPTION


    This API provides a quick way to retrieve a list of resources (corpora, lexicons, models, analyses,
    and utilities)

    available at Språkbanken Text. It is used to display resources on [Språkbanken Text''s

    website](https://spraakbanken.gu.se/en/resources).


    The main endpoint `/` lists metadata for all resources (unless the `resource` or `resource_type` parameter
    is used).

    Each resource is represented as a JSON object that adheres to the JSON schema available from the `/schema`
    endpoint.


    Some resources have detailed descriptions that are only displayed when using the `resource` parameter.
    For more

    information, please refer to the [GitHub repository](https://github.com/spraakbanken/metadata).'
  contact:
    name: Språkbanken Text
    url: https://spraakbanken.gu.se/
    email: sb-info@svenska.gu.se
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  version: 3.3.1
  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://ws.spraakbanken.gu.se/ws/metadata/v3/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/.
paths:
  /:
    get:
      tags:
      - Metadata retrieval
      summary: List all resources
      description: 'List metadata for all resources, all resources of a given type or a single resource
        by ID.


        Refer to the `/schema` endpoint for the exact JSON schema of the metadata.'
      operationId: list_resources__get
      parameters:
      - name: resource-type
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/ResourceTypes'
          - type: 'null'
          title: Resource type
          enum:
          - corpus
          - lexicon
          - model
          - analysis
          - utility
          - collection
        example: corpus
      - name: resource
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Resource ID
        example: attasidor
      - name: legacy
        in: query
        required: false
        schema:
          type: boolean
          description: If true, use legacy response format ('corpora' instead of 'corpus' etc.).
          default: true
          title: Legacy
        description: If true, use legacy response format ('corpora' instead of 'corpus' etc.).
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllResouresList'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /list-ids:
    get:
      tags:
      - Metadata retrieval
      summary: List resource IDs
      description: List all resource IDs.
      operationId: list_ids_list_ids_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  type: string
                type: array
                title: Response List Ids List Ids Get
  /bibtex:
    get:
      tags:
      - Metadata retrieval
      summary: Get BibTeX citation
      description: Return bibtex citation as text.
      operationId: bibtex_bibtex_get
      parameters:
      - name: resource
        in: query
        required: true
        schema:
          type: string
          title: Resource ID
        example: attasidor
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BibtexResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /corpora:
    get:
      tags:
      - Metadata retrieval
      summary: List corpus
      description: 'List all resources of type ''corpus''.


        Please use `/?resource-type=corpus` route instead.


        Refer to the /schema endpoint for the exact JSON schema of the metadata.'
      operationId: resource_list_corpora_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'
      deprecated: true
  /lexicons:
    get:
      tags:
      - Metadata retrieval
      summary: List lexicon
      description: 'List all resources of type ''lexicon''.


        Please use `/?resource-type=lexicon` route instead.


        Refer to the /schema endpoint for the exact JSON schema of the metadata.'
      operationId: resource_list_lexicons_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'
      deprecated: true
  /models:
    get:
      tags:
      - Metadata retrieval
      summary: List model
      description: 'List all resources of type ''model''.


        Please use `/?resource-type=model` route instead.


        Refer to the /schema endpoint for the exact JSON schema of the metadata.'
      operationId: resource_list_models_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'
      deprecated: true
  /analyses:
    get:
      tags:
      - Metadata retrieval
      summary: List analysis
      description: 'List all resources of type ''analysis''.


        Please use `/?resource-type=analysis` route instead.


        Refer to the /schema endpoint for the exact JSON schema of the metadata.'
      operationId: resource_list_analyses_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'
      deprecated: true
  /utilities:
    get:
      tags:
      - Metadata retrieval
      summary: List utility
      description: 'List all resources of type ''utility''.


        Please use `/?resource-type=utility` route instead.


        Refer to the /schema endpoint for the exact JSON schema of the metadata.'
      operationId: resource_list_utilities_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'
      deprecated: true
  /collections:
    get:
      tags:
      - Metadata retrieval
      summary: List collections
      description: 'List all resource collections.


        Refer to the `/schema` endpoint for the exact JSON schema of the metadata.'
      operationId: list_collections_collections_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionsList'
      deprecated: true
  /check-id-availability:
    get:
      tags:
      - MISC
      summary: Check resource ID availability
      description: Check if a given resource ID is available.
      operationId: check_id_check_id_availability_get
      parameters:
      - name: id
        in: query
        required: true
        schema:
          type: string
          title: Resource ID
        example: my-new-resource
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdAvailabilityResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /schema:
    get:
      tags:
      - MISC
      summary: Schema
      description: Return JSON schema for the metadata.
      operationId: schema_schema_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Schema Schema Get
  /renew-cache:
    get:
      tags:
      - Cache management
      summary: Renew Cache Get
      description: 'Trigger cache renewal as a background job (GET).


        Resources specified in the "resource-paths" query parameter will be reprocessed. If no resources
        are specified, all

        resources are reprocessed.'
      operationId: renew_cache_get_renew_cache_get
      parameters:
      - name: resource-paths
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Comma-separated list of specific resources to reprocess (<resource_type/resource_id>).
          title: Resource-Paths
        description: Comma-separated list of specific resources to reprocess (<resource_type/resource_id>).
        example: corpus/attasidor,lexicon/saldo
      - name: debug
        in: query
        required: false
        schema:
          type: boolean
          description: If true, log debug info while parsing YAML files.
          default: false
          title: Debug
        description: If true, log debug info while parsing YAML files.
      - name: offline
        in: query
        required: false
        schema:
          type: boolean
          description: If true, skip getting file info for downloadables.
          default: false
          title: Offline
        description: If true, skip getting file info for downloadables.
      - name: purge-license-cache
        in: query
        required: false
        schema:
          type: boolean
          description: If true, re-download the license information before parsing YAML files.
          default: false
          title: Purge-License-Cache
        description: If true, re-download the license information before parsing YAML files.
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenewCacheResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Cache management
      summary: Renew Cache Post
      description: 'Trigger cache renewal as a background job (POST).


        The resources to be reprocessed are determined based on the changed files in the webhook payload.'
      operationId: renew_cache_post_renew_cache_post
      parameters:
      - name: debug
        in: query
        required: false
        schema:
          type: boolean
          description: If true, log debug info while parsing YAML files.
          default: false
          title: Debug
        description: If true, log debug info while parsing YAML files.
      - name: offline
        in: query
        required: false
        schema:
          type: boolean
          description: If true, skip getting file info for downloadables.
          default: false
          title: Offline
        description: If true, skip getting file info for downloadables.
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - type: object
                additionalProperties: true
              - type: 'null'
              description: Payload from GitHub webhook.
              title: Payload
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenewCacheResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /openapi.json:
    get:
      tags:
      - Documentation
      summary: OpenAPI schema
      description: Serve the OpenAPI specification as JSON data.
      operationId: openapi_json_openapi_json_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /doc:
    get:
      tags:
      - Documentation
      summary: OpenAPI schema
      description: Serve the same JSON as /openapi.json (Backward-compatible alias).
      operationId: openapi_alias_doc_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Openapi Alias Doc Get
      deprecated: true
  /redoc:
    get:
      tags:
      - Documentation
      summary: ReDoc API documentation
      description: Serve ReDoc documentation.
      operationId: overridden_redoc_redoc_get
      responses:
        '200':
          description: Successful Response
          content:
            text/html:
              schema:
                type: string
  /docs:
    get:
      tags:
      - Documentation
      summary: Swagger UI documentation
      description: Serve Swagger UI documentation.
      operationId: overridden_swagger_docs_get
      responses:
        '200':
          description: Successful Response
          content:
            text/html:
              schema:
                type: string
components:
  schemas:
    AllResouresList:
      properties:
        corpus:
          items:
            $ref: '#/components/schemas/Resource'
          type: array
          title: Corpus
          description: List of corpus resources
        lexicon:
          items:
            $ref: '#/components/schemas/Resource'
          type: array
          title: Lexicon
          description: List of lexicon resources
        model:
          items:
            $ref: '#/components/schemas/Resource'
          type: array
          title: Model
          description: List of model resources
        analysis:
          items:
            $ref: '#/components/schemas/Resource'
          type: array
          title: Analysis
          description: List of analysis resources
        utility:
          items:
            $ref: '#/components/schemas/Resource'
          type: array
          title: Utility
          description: List of utility resources
      type: object
      required:
      - corpus
      - lexicon
      - model
      - analysis
      - utility
      title: AllResouresList
      description: List of all metadata resources, grouped by resource type.
    BibtexResponse:
      properties:
        bibtex:
          type: string
          title: Bibtex
          description: BibTeX citation as text
          examples:
          - "@misc{attasidor,\n  doi = {10.23695/f6ds-f045},\n  url = {https://spraakbanken.gu.se/resurser/attasidor},\n\
            \            \n  author = {Språkbanken Text},\n  keywords = {Language Technology (Computational\
            \ Linguistics)},\n            \n  language = {swe},\n  title = {8 Sidor},\n  publisher = {Språkbanken\
            \ Text},\n  year = {2024}\n}"
      type: object
      required:
      - bibtex
      title: BibtexResponse
      description: Response model for BibTeX entries.
    CollectionsList:
      properties:
        hits:
          type: integer
          title: Hits
          description: Number of collections in the list
          examples:
          - 5
        resources:
          items:
            $ref: '#/components/schemas/Resource'
          type: array
          title: Resources
      type: object
      required:
      - hits
      - resources
      title: CollectionsList
      description: List of resource collections.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    IdAvailabilityResponse:
      properties:
        id:
          type: string
          title: Id
          description: The resource ID that was checked
          examples:
          - my-new-resource
        available:
          type: boolean
          title: Available
          description: Indicates whether the resource ID is available
          examples:
          - true
          - false
      type: object
      required:
      - id
      - available
      title: IdAvailabilityResponse
      description: Response model for resource ID availability check.
    RenewCacheResponse:
      properties:
        task_id:
          type: string
          title: Task Id
          description: ID of the cache renewal task
          examples:
          - c09e5583-dd05-4949-9734-e02b60fad42a
        message:
          type: string
          title: Message
          description: Message indicating the status of the cache renewal request
          examples:
          - Cache renewal triggered in background.
      type: object
      required:
      - task_id
      - message
      title: RenewCacheResponse
      description: Response model for cache renewal requests.
    Resource:
      properties:
        id:
          type: string
          title: Id
          description: Unique identifier for the resource
          examples:
          - attasidor
        type:
          type: string
          title: Type
          description: Type of the resource
          examples:
          - corpus
          - lexicon
          - model
          - analysis
          - utility
        name:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Name
          description: Name of the resource in multiple languages
          examples:
          - en: 8 SIDOR
            sv: 8 SIDOR
        short_description:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Short Description
          description: Short description of the resource in multiple languages
          examples:
          - en: News articles from 8 SIDOR.
            sv: Nyhetsartiklar från 8 SIDOR.
      additionalProperties: true
      type: object
      required:
      - id
      - type
      title: Resource
      description: Metadata resource; keep permissive.
    ResourceList:
      properties:
        resource_type:
          type: string
          title: Resource Type
          description: Type of the resources
          examples:
          - corpus
          - lexicon
          - model
          - analysis
          - utility
        hits:
          type: integer
          title: Hits
          description: Number of resources in the list
          examples:
          - 42
        resources:
          items:
            $ref: '#/components/schemas/Resource'
          type: array
          title: Resources
      type: object
      required:
      - resource_type
      - hits
      - resources
      title: ResourceList
      description: List of metadata resources.
    ResourceTypes:
      type: string
      enum:
      - corpus
      - lexicon
      - model
      - analysis
      - utility
      - collection
      title: ResourceTypes
    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
tags:
- name: Metadata retrieval
  description: Endpoints for retrieving metadata about resources
- name: MISC
  description: Miscellaneous endpoints
- name: Cache management
  description: Endpoints for managing the metadata cache
- name: Documentation
  description: Endpoints for API documentation
servers:
- url: https://ws.spraakbanken.gu.se/ws/metadata/v3
  description: Production server
- url: https://ws.spraakbanken.gu.se/ws/metadata/dev
  description: Development server