openapi: 3.2.0
info:
  title: Bird Named Entity Recognition API
  description: The MessageBird Named Entity Recognition (NER) API extracts and parses a fixed set of entities from incoming phrases. A phrase is usually the text from an incoming message of your customer. An entity contains structured information such as person names, time, durations, locations, etc. Going from an unstructured phrase to structured data is helpful for building intelligent conversational systems such as chatbots.
  version: 1.0.0
  contact:
    name: Bird Support
    url: https://bird.com/en-us/contact
servers:
- url: https://ner.messagebird.com
security:
- AccessKey: []
tags:
- name: Named Entity Recognition
  description: Named entity recognition operations.
paths:
  /api/v1/predict-entities:
    post:
      tags:
      - Named Entity Recognition
      summary: Extract named entities from a phrase
      description: Extracts named entities from a phrase. If no entities can be found, returns an empty collection. Each entity contains one or more (possibly ambiguous) interpretations. You can limit the entity types to search for by explicitly providing them. If no language is specified, the API will try to infer it automatically.
      operationId: NamedEntityRecognition_PredictEntities
      security:
      - AccessKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PredictEntitiesRequest'
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PredictEntitiesResponse'
        '401':
          description: Returned when the user is not authorized.
        '404':
          description: Returned when the resource does not exist.
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/supported-languages:
    get:
      tags:
      - Named Entity Recognition
      summary: Get supported languages
      description: Lists the supported entity types per language.
      operationId: NamedEntityRecognition_ListSupportedLanguages
      security:
      - AccessKey: []
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSupportedLanguagesResponse'
        '401':
          description: Returned when the user is not authorized.
        '404':
          description: Returned when the resource does not exist.
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    PredictEntitiesRequest:
      type: object
      description: A request for extracting named entities from a phrase.
      required:
      - phrase
      properties:
        phrase:
          type: string
          example: I would like to go to Amsterdam on Sunday at 3pm for 2 hours.
          description: The phrase from which to extract named entities.
        language:
          type: string
          example: ENG
          description: 'The ISO-639-3 language code of the phrase. If not specified, the API will try to infer the language automatically.

            '
        entityTypes:
          type: array
          items:
            type: string
          example:
          - LOCATION
          - DATE_TIME
          description: 'The entity types to extract. If not specified, all entity types will be extracted.

            '
    ListSupportedLanguagesResponse:
      type: object
      description: A response containing the supported languages and their entity types.
      properties:
        languages:
          type: array
          items:
            $ref: '#/components/schemas/SupportedLanguageEntry'
          description: The collection of supported languages with their entity types.
    PredictEntitiesResponse:
      type: object
      description: 'A response containing the extracted named entities. If no entities can be found, an empty collection is returned.

        '
      properties:
        entities:
          type: array
          items:
            $ref: '#/components/schemas/Entity'
          description: The collection of recognized named entities.
    EntityValue:
      type: object
      description: A structured value for a recognized entity.
      properties:
        type:
          type: string
          example: LOCATION
          description: The entity type.
        value:
          type: object
          additionalProperties: true
          description: The structured value of the entity (varies by type).
    Entity:
      type: object
      description: A recognized named entity with one or more possible interpretations.
      properties:
        entityType:
          type: string
          example: LOCATION
          description: The type of the recognized entity.
        text:
          type: string
          example: Amsterdam
          description: The original text span from the phrase.
        startIndex:
          type: integer
          example: 22
          description: The start character index of the entity in the phrase.
        endIndex:
          type: integer
          example: 31
          description: The end character index (exclusive) of the entity in the phrase.
        values:
          type: array
          items:
            $ref: '#/components/schemas/EntityValue'
          description: 'One or more possible interpretations of this entity. Most recognized entities will contain only one interpretation.

            '
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        details:
          type: array
          items:
            type: object
            additionalProperties: true
    SupportedLanguageEntry:
      type: object
      description: A language and its supported entity types.
      properties:
        languageCode:
          type: string
          example: ENG
          description: The ISO-639-3 language code.
        languageName:
          type: string
          example: English
          description: The English name of the language.
        supportedEntityTypes:
          type: array
          items:
            type: string
          example:
          - DATE_TIME
          - LOCATION
          - PERSON
          description: The entity types supported for this language.
  securitySchemes:
    AccessKey:
      type: apiKey
      name: Authorization
      in: header
      description: 'Use the word "AccessKey" followed by your API Key. Example: "AccessKey w223tVQTcLO4ufBTuJxjvzwJ22"

        '
externalDocs:
  description: Find our official documentation in the MessageBird Docs
  url: https://developers.messagebird.com/api