Sparv API v3 — Text Annotation Pipeline

# x-method: searched
# x-source-url: https://raw.githubusercontent.com/spraakbanken/sparv-backend/oas-adapt/app/static/sparv_api_spec.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.0.2
info:
  title: Sparv API
  description: 'Sparv is Språkbanken Text''s text-annotation pipeline, exposed as a job-submission web
    service. Institution-operated: declared servers are https://ws.spraakbanken.gu.se/ws/sparv/v3 (production)
    and .../sparvlabb/v3 (lab), info.contact is sb-info@svenska.gu.se. Verified live 2026-09-01: GET /ws/sparv/v3/ping
    returned HTTP 200 {"message": "PONG"}.


    ---


    UPSTREAM DESCRIPTION


    Sparv is Språkbanken’s annotation tool and contains a corpus import pipeline

    and a web service including a [web interface](https://spraakbanken.gu.se/sparv/).

    It can be used to annotate shorter texts using the same tools as are applied

    in the annotation of the corpora in [Korp](https://spraakbanken.gu.se/korp) and the texts in

    [Strix](https://spraakbanken.gu.se/strix).


    You can read more about Sparv on [Språkbanken''s web page](https://spraakbanken.gu.se/eng/research/infrastructure/sparv).'
  x-logo:
    url: https://ws.spraakbanken.gu.se/ws/sparv/v3/static/sparv_frame.png
  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.0'
  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://raw.githubusercontent.com/spraakbanken/sparv-backend/oas-adapt/app/static/sparv_api_spec.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/.
servers:
- url: https://ws.spraakbanken.gu.se/ws/sparv/v3
  description: Production server
- url: https://ws.spraakbanken.gu.se/ws/sparvlabb/v3
  description: Lab version
tags:
- name: Analysis
  description: '### Queries for Annotating Texts


    The default query for the text analysis can be sent as GET or POST requests.

    The latter can be useful for longer texts. In both cases the response is a JSON

    object containing the text analysis in XML format.

    See [Default query](#tag/Analysis/paths/~1/get) for more details.


    It is also possible to upload text or XML files.

    In this case the response is a JSON object with a download link to a zip file

    containing the annotation.

    See [File upload](#tag/Files/paths/~1upload/post) for more details.


    ### Settings

    The web service supports some custom settings, e.g. it lets you choose

    between different tokenizers on word, sentence, and paragraph level

    and you can define which annotations should be generated. Via the settings you

    can also choose the language of your input and you can define whether your input

    is in XML or plain text.


    These settings are provided as a JSON object to the `settings` parameter.

    This object must satisfy the JSON schema that is generated by `/schema` call

    when provided with a `language` and a `mode` parameter:


    [`/schema?language=sv&mode=plain`](https://ws.spraakbanken.gu.se/ws/sparv/v3/schema?language=sv&mode=plain)


    The schema holds default values for all the attributes. The use of the settings

    parameter is therefore optional.


    This is an example for a request which only generates a dependency analysis:


    [`/?text=Det+trodde+jag+aldrig.&settings={"positional_attributes":{"dependency_attributes":["ref","dephead","deprel"],"lexical_attributes":[],"compound_attributes":[]}}`](https://ws.spraakbanken.gu.se/ws/sparv/v3/?text=Det+trodde+jag+aldrig.&settings={"positional_attributes":{"dependency_attributes":["ref","dephead","deprel"],"lexical_attributes":[],"compound_attributes":[]}})


    If you are not sure how to define the settings parameter you can get help

    from the [frontend](https://spraakbanken.gu.se/sparv) by clicking

    `Show JSON Settings` under `Show advanced settings`. This will generate

    the JSON object for the chosen settings which is sent in the `settings` parameter.


    ### Analysing other Languages


    The default analysis language is Swedish but Sparv

    also supports other languages. The language is specified by supplying

    a two-letter ISO 639-1 code to the `language` parameter.


    This is an example for an analysis of a German sentence:


    [`/?text=Nun+folgt+ein+deutscher+Beispielsatz.&language=de`](https://ws.spraakbanken.gu.se/ws/sparv/v3/?text=Nun+folgt+ein+deutscher+Beispielsatz.&language=de)


    Different kinds of settings are supported for different languages, depending on which tool

    is used for the analysis. Please use the [frontend](https://spraakbanken.gu.se/sparv)

    if you want to check what options there are for a certain language.

    Alternatively you can check the JSON schema for the language you want to analyse by sending a schema
    request, e.g.:


    [`/schema?language=de`](https://ws.spraakbanken.gu.se/ws/sparv/v3/schema?language=de)


    [This language table](https://spraakbanken.gu.se/eng/research/infrastructure/sparv/distribution/pipeline#language_table)

    provides information on which languages are currently supported and which tools are used for their
    analysis.

    '
- name: General
- name: Files
  description: File upload and download.
- name: Cleanup
  description: Calls for removing builds.
paths:
  /:
    get:
      tags:
      - Analysis
      summary: Default query
      description: 'When provided with the text parameter this call handles text input and runs the Sparv
        analysis.


        ### Example


        [`/?text=En+exempelmening+till+nättjänsten`](https://ws.spraakbanken.gu.se/ws/sparv/v3/?text=En+exempelmening+till+nättjänsten)

        '
      parameters:
      - name: text
        in: query
        required: true
        description: The text to be analysed
        schema:
          type: string
      - $ref: '#/components/parameters/ModeParam'
      - $ref: '#/components/parameters/IncrementalParam'
      - $ref: '#/components/parameters/LanguageParam'
      - $ref: '#/components/parameters/SettingsParam'
      responses:
        '200':
          description: Text analysis in XML
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalysisSchema'
        '500':
          description: Failed to run analysis
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
    post:
      tags:
      - Analysis
      summary: Default query
      description: 'When provided with the text parameter this call handles text input and runs the Sparv
        analysis.


        ### Example


        ```.bash

        curl -X POST --data-binary text="En exempelmening till nättjänsten" https://ws.spraakbanken.gu.se/ws/sparv/v3/

        ```

        '
      parameters:
      - name: text
        in: query
        required: true
        description: The text to be analysed
        schema:
          type: string
      - $ref: '#/components/parameters/ModeParam'
      - $ref: '#/components/parameters/IncrementalParam'
      - $ref: '#/components/parameters/LanguageParam'
      - $ref: '#/components/parameters/SettingsParam'
      responses:
        '200':
          description: Text analysis in XML
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalysisSchema'
        '500':
          description: Failed to run analysis
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /schema:
    get:
      tags:
      - Analysis
      summary: Schema
      description: 'Returns the json schema generated from the provided parameters.


        ### Example


        [`/schema?language=sv&mode=plain`](https://ws.spraakbanken.gu.se/ws/sparv/v3/schema?language=sv&mode=plain)

        '
      parameters:
      - $ref: '#/components/parameters/ModeParam'
      - $ref: '#/components/parameters/LanguageParam'
      - $ref: '#/components/parameters/MinifyParam'
      responses:
        '200':
          description: OK (schema returned)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettingsSchema'
        '500':
          description: Failed to return schema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /makefile:
    get:
      tags:
      - Analysis
      summary: Makefile
      description: 'Returns the Makefile generated from the provided parameters.


        ### Example


        [`/makefile?settings={"positional_attributes":{"dependency_attributes":["ref","dephead","deprel"],"lexical_attributes":[],"compound_attributes":[]}}`](https://ws.spraakbanken.gu.se/ws/sparv/v3/makefile?settings={"positional_attributes":{"dependency_attributes":["ref","dephead","deprel"],"lexical_attributes":[],"compound_attributes":[]}})

        '
      parameters:
      - $ref: '#/components/parameters/ModeParam'
      - $ref: '#/components/parameters/IncrementalParam'
      - $ref: '#/components/parameters/LanguageParam'
      - $ref: '#/components/parameters/SettingsParam'
      responses:
        '200':
          description: OK (Makefile returned)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MakefileSchema'
        '500':
          description: Failed to return Makefile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /join:
    get:
      tags:
      - Analysis
      summary: Join
      description: 'Joins an existing build.


        In the response of a text analysis you can find a hash number. This hash can be used to join an
        earlier build.


        The response contains the chosen settings, the original text and the result of the annotation.

        '
      parameters:
      - $ref: '#/components/parameters/IncrementalParam'
      - $ref: '#/components/parameters/HashParam'
      responses:
        '200':
          description: The settings, original input text and text analysis in XML
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JoinSchema'
        '500':
          description: Failed to join build
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /status:
    get:
      tags:
      - General
      summary: Status
      description: Returns the status of existing builds.
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: OK (successfully authenticated)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusSchema'
        '401':
          description: 'Failed to show status: secret key could not be confirmed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '500':
          description: Failed to show status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /ping:
    get:
      tags:
      - General
      summary: Ping backend
      description: 'Pings the backend, responds with the status of the catapult.


        ### Example


        [`/ping`](https://ws.spraakbanken.gu.se/ws/sparv/v3/ping)

        '
      responses:
        '200':
          description: OK (catapult responds)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PingSchema'
        '500':
          description: Failed to ping catapult
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /upload:
    post:
      tags:
      - Files
      summary: File upload
      description: 'Handles file uploads and runs the analysis.


        ### Example


        ```.bash

        curl -X POST -F files[]=@/path/to/file/myfile.txt https://ws.spraakbanken.gu.se/ws/sparv/v3/upload?

        ```

        '
      parameters:
      - $ref: '#/components/parameters/ModeParam'
      - $ref: '#/components/parameters/IncrementalParam'
      - $ref: '#/components/parameters/LanguageParam'
      - $ref: '#/components/parameters/SettingsParam'
      - name: email
        in: query
        required: false
        description: The user's email address
        schema:
          type: string
          default: ''
      requestBody:
        description: Files to be uploaded and analysed
        required: true
        content:
          text/plain:
            schema:
              type: string
              format: binary
          text/xml:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: Download link
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileSchema'
        '500':
          description: Analysis failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /download:
    get:
      tags:
      - Files
      summary: File download
      description: Handles download of result files.
      parameters:
      - $ref: '#/components/parameters/HashParam'
      responses:
        '200':
          description: Zip file downloaded
          content:
            application/zip:
              schema:
                type: string
                format: binary
        '500':
          description: Download failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /cleanup:
    get:
      tags:
      - Cleanup
      summary: Cleanup
      description: 'Removes builds that are finished and haven’t been accessed within the timeout (default:
        7 days).'
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: OK (old builds removed)
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/Cleanup'
                - $ref: '#/components/schemas/NoCleanup'
        '401':
          description: 'Cleanup failed: secret key could not be confirmed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '500':
          description: Failed to remove builds
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /cleanup/errors:
    get:
      tags:
      - Cleanup
      summary: Cleanup errors
      description: 'Removes builds that are finished and haven’t been accessed within the timeout (default:
        7 days) and the builds with status Error.'
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: OK (cleanup succeeded)
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/Cleanup'
                - $ref: '#/components/schemas/NoCleanup'
        '401':
          description: 'Cleanup failed: secret key could not be confirmed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '500':
          description: Failed to remove builds
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /cleanup/forceone:
    get:
      tags:
      - Cleanup
      summary: Cleanup one build
      description: Removes a single build.
      parameters:
      - $ref: '#/components/parameters/HashParam'
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: OK (build removed)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CleanupOne'
        '400':
          description: No hash supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        '401':
          description: 'Cleanup failed: secret key could not be confirmed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '500':
          description: Failed to remove build
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /cleanup/forceall:
    get:
      tags:
      - Cleanup
      summary: Cleanup all builds
      description: Removes all the existing builds.
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: OK (builds removed)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cleanup'
        '401':
          description: 'Cleanup failed: secret key could not be confirmed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '500':
          description: Failed to remove builds
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: secret_key
  parameters:
    SettingsParam:
      name: settings
      in: query
      required: false
      description: The settings to be used for the analysis. Must satisfy a shema retrieved from [Schema](#tag/Analysis/paths/~1schema/get).
      schema:
        $ref: '#/components/schemas/SettingsSchema'
    ModeParam:
      name: mode
      in: query
      required: false
      description: The input mode
      schema:
        type: string
        default: plain
        enum:
        - plain
        - xml
        - file
    IncrementalParam:
      name: incremental
      in: query
      required: false
      description: 'Set to `true` if you want to receive more information on how the analysis is being
        processed.

        Note: Incremental information can only be displayed if your query is run for the first time.

        The progress information is not available for older builds.

        '
      schema:
        type: boolean
        default: false
    HashParam:
      name: hash
      in: query
      required: true
      description: Hash of the analysis
      schema:
        type: string
    MinifyParam:
      name: minify
      in: query
      required: false
      description: If set to true, some attributes needed for the frontend will be excluded from the response.
      schema:
        type: boolean
        default: false
    LanguageParam:
      name: language
      in: query
      required: false
      description: 'The language of the text to be analysed.

        Check [this language table](https://spraakbanken.gu.se/eng/research/infrastructure/sparv/distribution/pipeline#language_table)
        for more information.

        '
      schema:
        type: string
        default: sv
        enum:
        - it
        - de
        - sv-1800
        - bg
        - ca
        - ru
        - nl
        - pl
        - fr
        - es
        - sv-dev
        - ro
        - la
        - sk
        - pt
        - sl
        - et
        - fi
        - gl
        - en
        - sv
        - 'no'
  schemas:
    StatusSchema:
      type: object
      properties:
        builds:
          type: array
          items:
            properties:
              accessed:
                type: string
                example: '2018-05-11 18:29:57'
              accessed-secs-ago:
                type: integer
                example: 326021.5
              hash:
                type: string
                example: d91d063efb5a8439643147c7367e3a4ddad5ec63
              since:
                type: string
                example: '2018-05-11 18:48:32'
              status:
                type: string
                example: Done
    PingSchema:
      type: object
      properties:
        message:
          type: string
          example: PONG
        time:
          type: integer
          example: 0.0081
    GeneralError:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              example: Some error message
    AuthenticationError:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              example: Authentication failed.
    MakefileSchema:
      type: object
      properties:
        makefile:
          type: string
          example: 'include $(SPARV_MAKEFILES)/Makefile.config

            corpus = untitled

            original_dir = original


            vrt_columns_annotations = word pos msd baseform lemgram sense complemgram compwf sentiment
            sentimentclass ref dephead.ref deprel

            vrt_columns             = word pos msd lemma    lex     sense complemgram compwf sentiment
            sentimentclass ref dephead     deprel


            vrt_structs_annotations = sentence.id paragraph.n text text.lix text.ovix text.nk

            vrt_structs             = sentence:id paragraph   text text:lix text:ovix text:nk


            xml_elements    = text

            xml_annotations = text


            token_chunk = sentence

            token_segmenter = better_word


            sentence_chunk = paragraph

            sentence_segmenter = punkt_sentence


            paragraph_chunk = text

            paragraph_segmenter = blanklines


            include $(SPARV_MAKEFILES)/Makefile.rules

            '
    FileSchema:
      type: object
      properties:
        build:
          type: object
          properties:
            hash:
              type: string
              example: a1b1de8f3508c5928352dbfc538025231a336801-f
            type:
              type: string
              example: files
        result:
          type: object
          properties:
            link:
              type: string
              example: https://ws.spraakbanken.gu.se/ws/sparv/v3/download?hash=a1b1de8f3508c5928352dbfc538025231a336801-f
    Cleanup:
      type: object
      properties:
        removed-builds:
          example:
          - d91d063efb5a8439643147c7367e3a4ddad5ec63
          - a1b1de8f3508c5928352dbfc538025231a336801-f
          items:
            type: array
            format: string
    CleanupOne:
      type: object
      properties:
        removed-builds:
          example:
          - d91d063efb5a8439643147c7367e3a4ddad5ec63
          items:
            type: array
            format: string
    NoCleanup:
      type: object
      properties:
        message:
          type: string
          example: No hashes to be removed.
    AnalysisSchema:
      type: object
      properties:
        build:
          type: object
          properties:
            hash:
              type: string
              example: ece7233cc6fface3adeef4bfc5dc1e9fdfd94488
        result:
          type: object
          properties:
            link:
              type: string
              example: https://ws.spraakbanken.gu.se/ws/sparv/v3/download?hash=ece7233cc6fface3adeef4bfc5dc1e9fdfd94488
            analysis:
              type: string
              example: "<corpus>\n  <text lix=\"54.00\" ovix=\"inf\" nk=\"inf\">\n    <paragraph>\n  \
                \      <sentence id=\"8f7-84d\">\n            <w pos=\"DT\" msd=\"DT.UTR.SIN.IND\" lemma=\"\
                |en|\" lex=\"|en..al.1|\" sense=\"|den..1:-1.000|en..2:-1.000|\" complemgram=\"|\" compwf=\"\
                |\" sentiment=\"\" sentimentclass=\"\" ref=\"1\" dephead=\"2\" deprel=\"DT\">En</w>\n\
                \            <w pos=\"NN\" msd=\"NN.UTR.SIN.IND.NOM\" lemma=\"|exempelmening|\" lex=\"\
                |\" sense=\"|\" complemgram=\"|exempel..nn.1+mening..nn.1:1.090e-08|\" compwf=\"|exempel+mening|\"\
                \ sentiment=\"\" sentimentclass=\"\" ref=\"2\" dephead=\"\" deprel=\"ROOT\">exempelmening</w>\n\
                \            <w pos=\"PP\" msd=\"PP\" lemma=\"|till|\" lex=\"|till..pp.1|\" sense=\"|till..1:-1.000|\"\
                \ complemgram=\"|\" compwf=\"|\" sentiment=\"\" sentimentclass=\"\" ref=\"3\" dephead=\"\
                2\" deprel=\"ET\">till</w>\n            <w pos=\"NN\" msd=\"NN.UTR.SIN.DEF.NOM\" lemma=\"\
                |nättjänst|nättjänsten|\" lex=\"|\" sense=\"|\" complemgram=\"|nät..nn.1+tjänst..nn.2:5.711e-11|nät..nn.1+tjänst..nn.1:5.711e-11|nätt..av.1+tjänst..nn.1:1.004e-12|nätt..av.1+tjänst..nn.2:1.004e-12|nät..nn.1+tjäna..vb.1+sten..nn.2:2.049e-27|nät..nn.1+tjäna..vb.1+sten..nn.1:2.049e-27|nätt..av.1+tjäna..vb.1+sten..nn.2:4.784e-28|nätt..av.1+tjäna..vb.1+sten..nn.1:4.784e-28|\"\
                \ compwf=\"|nät+tjänsten|nätt+tjänsten|nät+tjän+sten|nätt+tjän+sten|\" sentiment=\"\"\
                \ sentimentclass=\"\" ref=\"4\" dephead=\"3\" deprel=\"PA\">nättjänsten</w>\n        </sentence>\n\
                \    </paragraph>\n  </text>\n</corpus>\n"
    JoinSchema:
      type: object
      properties:
        settings:
          $ref: '#/components/schemas/SettingsSchema'
        original:
          type: string
          example: '&lt;text&gt;En exempelmening till nättjänsten&lt;/text&gt;'
        analysis:
          $ref: '#/components/schemas/AnalysisSchema'
    SettingsSchema:
      type: object
      example:
        corpus: exempelkorpus
        lang: sv
        textmode: plain
        word_segmenter: default_tokenizer
        sentence_segmentation:
          sentence_chunk: paragraph
          sentence_segmenter: default_tokenizer
        paragraph_segmentation:
          paragraph_segmenter: blanklines
        positional_attributes:
          lexical_attributes:
          - pos
          - msd
          - lemma
          - lex
          - sense
          compound_attributes:
          - complemgram
          - compwf
          dependency_attributes:
          - ref
          - dephead
          - deprel
          sentiment:
          - sentiment
        named_entity_recognition: []
        text_attributes:
          readability_metrics:
          - lix
          - ovix
          - nk