LINDAT NameTag API

# Provenance: DERIVED by API Evangelist from the operator's own published REST API
# reference, then verified against live responses from the production host.
# UFAL publishes human documentation, not a machine-readable contract, for this service.
# method: derived
# x-source-url: https://lindat.mff.cuni.cz/services/nametag/api-reference.php
# generated: 2026-09-01
# x-operator: institution (Institute of Formal and Applied Linguistics, Faculty of
#   Mathematics and Physics, Charles University — host lindat.mff.cuni.cz is the
#   institution's own registrable domain)
openapi: 3.2.0
info:
  title: LINDAT NameTag API
  version: '3'
  summary: Named-entity recognition and tokenization web service operated by ÚFAL at Charles University.
  description: >-
    Public REST API for named-entity recognition and tokenization (NameTag 3) operated by the
    Institute of Formal and Applied Linguistics (ÚFAL), Faculty of Mathematics and Physics,
    Charles University, and delivered through the LINDAT/CLARIAH-CZ research infrastructure.
    The service is freely available without an API key; the underlying models are licensed
    CC BY-NC-SA and commercial exploitation requires explicit written permission of the authors.
    Derived by API Evangelist from the published REST API reference at
    https://lindat.mff.cuni.cz/services/nametag/api-reference.php and verified against live
    responses from https://lindat.mff.cuni.cz/services/nametag/api on 2026-09-01.
  contact:
    name: LINDAT/CLARIAH-CZ Helpdesk
    email: lindat-help@ufal.mff.cuni.cz
    url: https://lindat.mff.cuni.cz/user_feedback
  license:
    name: CC BY-NC-SA
    url: https://creativecommons.org/licenses/by-nc-sa/4.0/
  termsOfService: https://lindat.mff.cuni.cz/en/terms-of-use
servers:
  - url: https://lindat.mff.cuni.cz/services/nametag/api
    description: Production service operated by ÚFAL, Charles University
tags:
  - name: nametag
    description: Named-entity recognition and tokenization operations
paths:
  /models:
    get:
      operationId: listNameTagModels
      summary: List available NameTag models
      description: Returns the list of models available in the NameTag REST API, the methods each model supports, and the default model (guaranteed to be the latest Czech model).
      tags: [nametag]
      responses:
        '200':
          description: Model inventory
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelList'
  /recognize:
    get:
      operationId: recognizeEntities
      summary: Recognize named entities in supplied text
      tags: [nametag]
      parameters:
        - $ref: '#/components/parameters/Data'
        - $ref: '#/components/parameters/Model'
        - name: input
          in: query
          required: false
          description: Input format to use.
          schema:
            type: string
            enum: [untokenized, vertical, conllu]
            default: untokenized
        - name: output
          in: query
          required: false
          description: Output format to use.
          schema:
            type: string
            enum: [xml, vertical, conll, conllu-ne]
            default: xml
      responses:
        '200':
          description: Recognition result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceResponse'
    post:
      operationId: recognizeEntitiesPost
      summary: Recognize named entities in supplied text (form-encoded or file upload)
      tags: [nametag]
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/RecognizeRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/RecognizeRequest'
      responses:
        '200':
          description: Recognition result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceResponse'
  /tokenize:
    get:
      operationId: tokenizeText
      summary: Tokenize supplied text
      tags: [nametag]
      parameters:
        - $ref: '#/components/parameters/Data'
        - $ref: '#/components/parameters/Model'
        - name: output
          in: query
          required: false
          description: Output format to use.
          schema:
            type: string
            enum: [xml, vertical]
            default: xml
      responses:
        '200':
          description: Tokenization result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceResponse'
    post:
      operationId: tokenizeTextPost
      summary: Tokenize supplied text (form-encoded or file upload)
      tags: [nametag]
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenizeRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/TokenizeRequest'
      responses:
        '200':
          description: Tokenization result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceResponse'
components:
  parameters:
    Data:
      name: data
      in: query
      required: true
      description: Input text in UTF-8.
      schema:
        type: string
    Model:
      name: model
      in: query
      required: false
      description: Model to use. May be a full model name, a name without the -YYMMDD version suffix, or a prefix such as `czech` or `english`; the latest most suitable model is then used.
      schema:
        type: string
  schemas:
    ModelList:
      type: object
      description: Inventory of available models and the methods each supports.
      properties:
        models:
          type: object
          description: Map of model name to the list of methods that model supports.
          additionalProperties:
            type: array
            items:
              type: string
              enum: [recognize, tokenize]
        default_model:
          type: string
          description: Model used when the caller supplies none.
      required: [models, default_model]
    ServiceResponse:
      type: object
      description: Common LINDAT web-service response envelope.
      properties:
        model:
          type: string
          description: Model actually used to produce the result.
        acknowledgements:
          type: array
          description: URLs that must be acknowledged when the result is used.
          items:
            type: string
            format: uri
        result:
          type: string
          description: Output text in the requested output format.
      required: [model, result]
    RecognizeRequest:
      type: object
      properties:
        data:
          type: string
          description: Input text in UTF-8.
        model:
          type: string
        input:
          type: string
          enum: [untokenized, vertical, conllu]
        output:
          type: string
          enum: [xml, vertical, conll, conllu-ne]
      required: [data]
    TokenizeRequest:
      type: object
      properties:
        data:
          type: string
          description: Input text in UTF-8.
        model:
          type: string
        output:
          type: string
          enum: [xml, vertical]
      required: [data]