swagger: "2.0"
info:
  title: FAQ
  version: version not set
tags:
  - name: FAQ
    description: "The MessageBird FAQ API enables answering questions from an FAQ dataset created. Datasets can be created and managed using the [dataset section of the MessageBird Dashboard](https://dashboard.messagebird.com/knowledge-base/list). \n\nFAQ datasets are created by giving multiple variations of questions that correspond to an answer. There can be multiple answers, each with multiple corresponding questions. The MessageBird FAQ API applies machine learning to generalize from the questions and answers that you added to your datasets so that unseen questions are automatically mapped to the right answer. \n\nYou can view and edit the questions and answers in the [datasets section of the dashboard](https://dashboard.messagebird.com/knowledge-base/list). An effective way to iterate and improve the FAQ recognition accuracy is to leverage the Train UI that can be accessed from the [dataset overview](https://dashboard.messagebird.com/knowledge-base/list)."
host: faq.messagebird.com
schemes:
  - https
consumes:
  - application/json
produces:
  - application/json
paths:
  /api/v1/datasets:
    get:
      summary: List datasets
      description: Lists datasets containing answers and corresponding questions. You can choose to list only your own datasets, as well as template datasets, or both. You might need to iterate over multiple pages to obtain all of your datasets.
      operationId: FAQ_ListDatasets
      responses:
        "200":
          description: A successful response.
          schema:
            $ref: '#/definitions/v1ListDatasetsResponse'
        "401":
          description: Returned when the user is not authorized.
          schema: {}
        "404":
          description: Returned when the resource does not exist.
          schema: {}
        default:
          description: An unexpected error response.
          schema:
            $ref: '#/definitions/rpcStatus'
      parameters:
        - name: listMode
          description: |-
            The list mode indicating to query public datasets, only user datasets or both.

             - LIST_MODE_UNDEFINED: The list dataset mode type undefined.
             - ALL: List all datasets.
             - ONLY_TEMPLATE: List the template datasets. Template datasets are used as examples and can be found under the `Templates` tab in the [dataset overview of the dashboard](https://dashboard.messagebird.com/knowledge-base/list). You can clone such datasets to kickstart the creation of a dataset that is tailored to your use-case.
             - ONLY_USER: List the user datasets.
          in: query
          required: false
          type: string
          enum:
            - LIST_MODE_UNDEFINED
            - ALL
            - ONLY_TEMPLATE
            - ONLY_USER
          default: LIST_MODE_UNDEFINED
          x-example: ONLY_USER
        - name: limit
          description: The limit defining the maximal number of datasets to return.
          in: query
          required: false
          type: integer
          format: int64
          default: "20"
        - name: cursor
          description: The cursor to view the next paginated collection of datasets as provided by the `next_cursor` value in the ListDatasetsResponse.
          in: query
          required: false
          type: string
          default: "null"
      tags:
        - FAQ
      security:
        - AccessKey: []
  /api/v1/datasets/{datasetId}:
    get:
      summary: Get dataset
      description: Retrieves the dataset for the given dataset ID.
      operationId: FAQ_GetDataset
      responses:
        "200":
          description: A successful response.
          schema:
            $ref: '#/definitions/v1Dataset'
        "401":
          description: Returned when the user is not authorized.
          schema: {}
        "404":
          description: Returned when the resource does not exist.
          schema: {}
        default:
          description: An unexpected error response.
          schema:
            $ref: '#/definitions/rpcStatus'
      parameters:
        - name: datasetId
          description: The unique ID for the dataset.
          in: path
          required: true
          type: string
      tags:
        - FAQ
      security:
        - AccessKey: []
  /api/v1/datasets/{datasetId}/predict-answer:
    post:
      summary: Predict Answer
      description: Predicts an answer corresponding to a question which is possibly contained in the phrase given an FAQ dataset. The FAQ API uses machine learning to generalize from the questions and answers in the dataset to infer the answer of the given question. This requires the active model for the dataset to be trained. Training a model usually takes around 1 minute after a dataset is created or updated. This endpoint yields an error if the model has not been trained yet.
      operationId: FAQ_PredictAnswer
      responses:
        "200":
          description: A successful response.
          schema:
            $ref: '#/definitions/v1PredictAnswerResponse'
        "401":
          description: Returned when the user is not authorized.
          schema: {}
        "404":
          description: Returned when the resource does not exist.
          schema: {}
        default:
          description: An unexpected error response.
          schema:
            $ref: '#/definitions/rpcStatus'
      parameters:
        - name: datasetId
          description: The unique ID that identifies the dataset for which a question should be answered.
          in: path
          required: true
          type: string
        - name: body
          in: body
          required: true
          schema:
            type: object
            example:
              phrase: Who founded MessageBird?
            properties:
              phrase:
                type: string
                example: Who founded MessageBird?
                description: The phrase that might contain a question to be answered.
                title: Phrase
            description: A request for predicting an answer from a phrase and a dataset ID.
            title: PredictAnswerRequest
      tags:
        - FAQ
      security:
        - AccessKey: []
  /api/v1/supported-languages:
    get:
      summary: Get supported languages.
      description: Lists the languages supported by the FAQ API.
      operationId: FAQ_ListSupportedLanguages
      responses:
        "200":
          description: A successful response.
          schema:
            $ref: '#/definitions/v1LanguageList'
        "401":
          description: Returned when the user is not authorized.
          schema: {}
        "404":
          description: Returned when the resource does not exist.
          schema: {}
        default:
          description: An unexpected error response.
          schema:
            $ref: '#/definitions/rpcStatus'
      tags:
        - FAQ
      security:
        - AccessKey: []
definitions:
  protobufAny:
    type: object
    properties:
      '@type':
        type: string
    additionalProperties: {}
  rpcStatus:
    type: object
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string
      details:
        type: array
        items:
          $ref: '#/definitions/protobufAny'
  v1Answer:
    type: object
    example:
      text: Messagebird was founded by Robert Vis in 2011.
      title: MessageBird Founder
      url: https://messagebird.com/en/about
    properties:
      text:
        type: string
        example: Messagebird was founded by Robert Vis in 2011.
        description: The text containing the answer.
        title: Text
      url:
        type: string
        example: https://messagebird.com/en/about
        description: The URL with additional information for this answer.
        title: Url
      title:
        type: string
        example: MessageBird Founder
        description: The short title representing the answer.
        title: Title
    description: An answer which corresponds to one or more example questions in the dataset.
    title: Answer
  v1Dataset:
    type: object
    example:
      createdAt: "2021-08-24T12:04:32Z"
      datasetId: dde4eeae-7652-4bc8-8be1-1cd6ac898dc7
      description: This dataset has a list of frequently asked questions about MessageBird
      isTemplate: false
      lastTrainedAt: "2021-08-24T12:04:32Z"
      name: MessageBird FAQ
      updatedAt: "2021-08-24T12:04:32Z"
    properties:
      datasetId:
        type: string
        format: uuid
        example: dde4eeae-7652-4bc8-8be1-1cd6ac898dc7
        description: The unique ID for the dataset.
        title: Dataset Id
        readOnly: true
      name:
        type: string
        example: MessageBird FAQ
        description: The name of the dataset.
        title: Name
      createdAt:
        type: string
        format: timestamp
        example: "2021-08-24T12:04:32Z"
        description: The timestamp of dataset creation. Uses the [ISO-8601 standard](https://en.wikipedia.org/wiki/ISO_8601).
        title: Created At
        readOnly: true
      updatedAt:
        type: string
        format: timestamp
        example: "2021-08-24T12:04:32Z"
        description: The timestamp of last update. Uses the [ISO-8601 standard](https://en.wikipedia.org/wiki/ISO_8601).
        title: Updated At
        readOnly: true
      isTemplate:
        type: boolean
        example: false
        description: Whether this dataset is a template dataset or not. Template datasets are used as examples and can be found under the `Templates` tab in the [dataset overview of the dashboard](https://dashboard.messagebird.com/knowledge-base/list). You can clone such datasets to kickstart the creation of a dataset that is tailored to your use-case.
        title: Is Template
        readOnly: true
      description:
        type: string
        example: This dataset has a list of frequently asked questions about MessageBird
        description: The optional description of the dataset.
        title: Description
      lastTrainedAt:
        type: string
        format: timestamp
        example: "2021-08-24T12:04:32Z"
        description: The timestamp of last model that completed training. Uses the [ISO-8601 standard](https://en.wikipedia.org/wiki/ISO_8601).
        title: Last Trained At
        readOnly: true
    description: A collection of answers with matching questions. There can be multiple matching questions per answer.
    title: Dataset
  v1Language:
    type: object
    example:
      iso6393Code: nld
      languageCode: NLD
      name: Dutch
    properties:
      iso6393Code:
        type: string
        example: nld
        description: The ISO-639-3 code of the language.
        title: Iso 639 3 Code
      name:
        type: string
        example: Dutch
        description: The English name of the language.
        title: Name
      languageCode:
        $ref: '#/definitions/v1LanguageCode'
        example: NLD
        description: The enum value of the ISO639-3 language code.
        title: Language Code
    description: Language that was detected from the given phrase.
    title: Language
  v1LanguageCode:
    type: string
    enum:
      - LANGUAGE_INVALID
      - LANGUAGE_UNDETERMINED
      - ENG
      - RUS
      - DEU
      - FRA
      - ITA
      - JPN
      - SPA
      - CEB
      - TUR
      - POR
      - UKR
      - EPO
      - POL
      - SWE
      - NLD
      - HEB
      - ZHO
      - HUN
      - ARA
      - CAT
      - FIN
      - CES
      - FAS
      - SRP
      - ELL
      - VIE
      - BUL
      - KOR
      - NOR
      - MKD
      - RON
      - IND
      - THA
      - HYE
      - DAN
      - TAM
      - HIN
      - HRV
      - HBS
      - BEL
      - KAT
      - TEL
      - KAZ
      - WAR
      - LIT
      - GLG
      - SLK
      - BEN
      - EUS
      - SLV
      - KAN
      - MAL
      - MAR
      - EST
      - AZE
      - MSA
      - SQI
      - LAT
      - BOS
      - NNO
      - URD
      - LAV
      - MYA
      - TAT
      - AFR
      - OCI
      - NDS
      - KIR
      - AST
      - TGL
      - ISL
      - INA
      - SIN
      - GUJ
      - KHM
      - BRE
      - BAK
      - UZB
      - BOD
      - PAN
      - VOL
      - ALS
      - NEP
      - CYM
      - JBO
      - FRY
      - MON
      - LTZ
      - CHE
      - UIG
      - TGK
      - SCO
      - SAN
      - CHV
      - JAV
      - MIN
      - IDO
      - ORI
      - ASM
      - NEW
      - GLE
      - MLG
      - ARG
      - CKB
      - SWA
      - BAR
      - LMO
      - YID
      - ARZ
      - MHR
      - AZB
      - SAH
      - PNB
      - SUN
      - BPY
      - PMS
      - ILO
      - WUU
      - KUR
      - PUS
      - ILE
      - XMF
      - YUE
      - GOM
      - LIM
      - MWL
      - COR
      - SND
      - HSB
      - SCN
      - GLA
      - PAM
      - BHO
      - MAI
      - VEC
      - MLT
      - DIV
      - WLN
      - MZN
      - AMH
      - QUE
      - CBK
      - TUK
      - ROH
      - OSS
      - VLS
      - YOR
      - LAO
      - LEZ
      - SOM
      - MYV
      - DIQ
      - MRJ
      - DSB
      - FRR
      - HAT
      - GRN
      - BXR
      - KOM
      - SRD
      - KRC
      - BCL
      - NAP
      - GLV
      - AVA
      - RUE
      - XAL
      - PFL
      - DTY
      - HIF
      - COS
      - LRC
      - VEP
      - TYV
      - NOB
      - SNA
      - KIN
      - IBO
      - SMO
      - SOT
      - MRI
      - WOL
      - XHO
      - HAU
      - HAW
      - NYA
      - ZUL
      - HMN
    default: LANGUAGE_INVALID
    valueComments:
      - Language code is invalid.
      - Language could not be determined.
      - English.
      - Russian.
      - German.
      - French.
      - Italian.
      - Japanese.
      - Spanish.
      - Cebuano.
      - Turkish.
      - Portuguese.
      - Ukrainian.
      - Esperanto.
      - Polish.
      - Swedish.
      - Dutch.
      - Hebrew.
      - Chinese.
      - Hungarian.
      - Arabic.
      - Catalan.
      - Finnish.
      - Czech.
      - Persian.
      - Serbian.
      - Greek.
      - Vietnamese.
      - Bulgarian.
      - Korean.
      - Norwegian.
      - Macedonian.
      - Romanian.
      - Indonesian.
      - Thai.
      - Armenian.
      - Danish.
      - Tamil.
      - Hindi.
      - Croatian.
      - Serbo-Croatian.
      - Belarusian.
      - Georgian.
      - Telugu.
      - Kazakh.
      - Waray.
      - Lithuanian.
      - Galician.
      - Slovak.
      - Bengali.
      - Basque.
      - Slovenian.
      - Kannada.
      - Malayalam.
      - Marathi.
      - Estonian.
      - Azerbaijani.
      - Malay.
      - Albanian.
      - Latin.
      - Bosnian.
      - Norwegian Nynorsk.
      - Urdu.
      - Latvian.
      - Burmese.
      - Tatar.
      - Afrikaans.
      - Occitan.
      - Low German.
      - Kirghiz.
      - Asturian.
      - Tagalog.
      - Icelandic.
      - Interlingua.
      - Sinhala.
      - Gujarati.
      - Central Khmer.
      - Breton.
      - Bashkir.
      - Uzbek.
      - Tibetan.
      - Panjabi.
      - Volapük.
      - Tosk Albanian.
      - Nepali.
      - Welsh.
      - Lojban.
      - Western Frisian.
      - Mongolian.
      - Luxembourgish.
      - Chechen.
      - Uighur.
      - Tajik.
      - Scots.
      - Sanskrit.
      - Chuvash.
      - Javanese.
      - Minangkabau.
      - Ido.
      - Oriya.
      - Assamese.
      - Newari.
      - Irish.
      - Malagasy.
      - Aragonese.
      - Central Kurdish.
      - Swahili.
      - Bavarian.
      - Lombard.
      - Yiddish.
      - Egyptian Arabic.
      - Eastern Mari.
      - South Azerbaijani.
      - Yakut.
      - Western Panjabi.
      - Sundanese.
      - Bishnupriya.
      - Piemontese.
      - Iloko.
      - Wu Chinese.
      - Kurdish.
      - Pushto.
      - Interlingue.
      - Mingrelian.
      - Yue Chinese.
      - Goan Konkani.
      - Limburgan.
      - Mirandese.
      - Cornish.
      - Sindhi.
      - Upper Sorbian.
      - Sicilian.
      - Scottish Gaelic.
      - Pampanga.
      - Bhojpuri.
      - Maithili.
      - Venetian.
      - Maltese.
      - Dhivehi.
      - Walloon.
      - Mazanderani.
      - Amharic.
      - Quechua.
      - Chavacano.
      - Turkmen.
      - Romansh.
      - Ossetian.
      - Vlaams.
      - Yoruba.
      - Lao.
      - Lezghian.
      - Somali.
      - Erzya.
      - Dimli.
      - Western Mari.
      - Lower Sorbian.
      - Northern Frisian.
      - Haitian.
      - Guarani.
      - Russia Buriat.
      - Komi.
      - Sardinian.
      - Karachay-Balkar.
      - Central Bikol.
      - Neapolitan.
      - Manx.
      - Avaric.
      - Rusyn.
      - Kalmyk.
      - Pfaelzisch.
      - Dotyali.
      - Fiji Hindi.
      - Corsican.
      - Northern Luri.
      - Veps.
      - Tuvinian.
      - Norwegian Bokmål.
      - Shona.
      - Kinyarwanda.
      - Igbo.
      - Samoan.
      - Southern Sotho.
      - Maori.
      - Wolof.
      - Xhosa.
      - Hausa.
      - Hawaiian.
      - Nyanja.
      - Zulu.
      - Hmong.
    description: 'Language code in ISO639-3 format. More info can be found here: https://iso639-3.sil.org/code_tables/639/data.'
  v1LanguageList:
    type: object
    example:
      languages:
        - iso6393Code: nld
          languageCode: NLD
          name: Dutch
        - iso6393Code: eng
          languageCode: ENG
          name: English
        - iso6393Code: spa
          languageCode: SPA
          name: Spanish
        - iso6393Code: zho
          languageCode: ZHO
          name: Chinese
    properties:
      languages:
        type: array
        example:
          - iso6393Code: nld
            languageCode: NLD
            name: Dutch
          - iso6393Code: eng
            languageCode: ENG
            name: English
          - iso6393Code: spa
            languageCode: SPA
            name: Spanish
          - iso6393Code: zho
            languageCode: ZHO
            name: Chinese
        items:
          $ref: '#/definitions/v1Language'
        description: The collection of languages.
        title: Languages
    description: List of recognized languages.
    title: LanguageList
  v1ListDatasetsMode:
    type: string
    enum:
      - LIST_MODE_UNDEFINED
      - ALL
      - ONLY_TEMPLATE
      - ONLY_USER
    default: LIST_MODE_UNDEFINED
    valueComments:
      - The list dataset mode type undefined.
      - List all datasets.
      - List the template datasets. Template datasets are used as examples and can be found under the `Templates` tab in the [dataset overview of the dashboard](https://dashboard.messagebird.com/knowledge-base/list). You can clone such datasets to kickstart the creation of a dataset that is tailored to your use-case.
      - List the user datasets.
    description: The list mode indicating to query public datasets, only user datasets or both.
  v1ListDatasetsResponse:
    type: object
    example:
      datasets:
        - createdAt: "2021-08-24T12:04:32Z"
          datasetId: dde4eeae-7652-4bc8-8be1-1cd6ac898dc7
          description: This dataset has a list of frequently asked questions about MessageBird
          isTemplate: false
          lastTrainedAt: "2021-08-24T12:04:32Z"
          name: MessageBird FAQ
          updatedAt: "2021-08-24T12:04:32Z"
      limit: 20
      nextCursor: VGhpcyBpcyBub3QgYSByZWFsIGN1cnNvciwgYnV0IHRoZXkgd291bGQgYmUgYmFzZTY0IGVuY29kZWQgdG9vCg==
    properties:
      datasets:
        type: array
        example:
          - createdAt: "2021-08-24T12:04:32Z"
            datasetId: dde4eeae-7652-4bc8-8be1-1cd6ac898dc7
            description: This dataset has a list of frequently asked questions about MessageBird
            isTemplate: false
            lastTrainedAt: "2021-08-24T12:04:32Z"
            name: MessageBird FAQ
            updatedAt: "2021-08-24T12:04:32Z"
        items:
          $ref: '#/definitions/v1Dataset'
        description: The (paginated) collection of datasets. This can contain both your own datasets as well as template datasets. Template datasets are used as examples and can be found under the `Templates` tab in the [dataset overview of the dashboard](https://dashboard.messagebird.com/knowledge-base/list). You can clone such datasets to kickstart the creation of a dataset that is tailored to your use-case.
        title: Datasets
      limit:
        type: integer
        format: int64
        example: 20
        description: The effective limit of the maximum number of datasets that could be returned by the list endpoint. If the `limit` defined in [`ListDatasetsRequest`](#listdatasetsrequest-object) was not set, this value indicates the used limit.
        title: Limit
      nextCursor:
        type: string
        example: VGhpcyBpcyBub3QgYSByZWFsIGN1cnNvciwgYnV0IHRoZXkgd291bGQgYmUgYmFzZTY0IGVuY29kZWQgdG9vCg==
        description: The cursor that can be used to query the next paginated collection of results.
        title: Next Cursor
    description: A response containing the FAQ datasets that were queried.
    title: ListDatasetsResponse
  v1PredictAnswerResponse:
    type: object
    example:
      answer:
        text: Messagebird was founded by Robert Vis in 2011.
        title: MessageBird Founder
        url: https://messagebird.com/en/about
      answerPredicted: false
    properties:
      answer:
        $ref: '#/definitions/v1Answer'
        example:
          text: Messagebird was founded by Robert Vis in 2011.
          title: MessageBird Founder
          url: https://messagebird.com/en/about
        description: The answer that is predicted for the given phrase. If no matching answer was found, this field will not be populated.
        title: Answer
      answerPredicted:
        type: boolean
        example: false
        description: Indicates if an answer was predicted. If `false`, the phrase could not be matched with an answer.
        title: Answer Predicted
    description: A response that contains the answer and its related metadata, such as a URL pointing to more details. If the FAQ API could not find a corresponding answer, the answer field will not be populated.
    title: PredictAnswerResponse
securityDefinitions:
  AccessKey:
    type: apiKey
    name: Authorization
    in: header
externalDocs:
  description: Find our official documentation in the MessageBird Docs
  url: https://developers.messagebird.com/api