AutoFAQ API
Описание
Вы можете использовать API для полного управления возможностями сервиса autoFAQ
  • создавать, редактировать и удалять базы знаний
  • создавать, редактировать и удалять документы в базе знаний
  • отправлять запросы к базе знаний и управлять ее дообучением.
В случае вопросов - пишите на наш e-mail.


Аутентификация
Для аутентификации необходимы следующие параметры:

  • user_id - уникальный номер пользователя
  • user_token - строковый ключ пользователя

  • service_id - уникальный номер базы знаний
  • service_token - строковый ключ базы знаний (может быть несколько)

Управление базами знаний требует user_id, user_token и service_id
Запросы и управление дообучением требуют service_id и service_token

user_id, user_token - выдаются при регистрации в сервисе через web интерфейс
service_id, service_token - возвращаются при создании новой БЗ через API, так же доступны через web интерфейс.

    Ошибки
    В случае ошибки, ответ системы содержит HTTP STATUS CODE не равный 200 и опционально описание ошибки в теле ответа.
    HTTP status codes:
    • 400 - bad query;
    • 401 - unauthorized;
    • 404 - not found;
    • 405 - method now allowed (when limits exceeded);
    • 429 - too many requests;
    • 500 - server side error.

    В случае ошибки, JSON тело ответа содержит поле error и текстовое описание ошибки.

    При добавлении и обновлении документов (напрямую или в рамках работы с БЗ) запускается механизм защиты - система вернет ошибку при попытке добавить близкий к существующим ответ или вопрос/формулировку вопроса. Степень близости регулируется параметрами защиты базы знаний:
    • max_trainable_score - порог оценки схожести вопросов и формулировок. Сервис не запомнит новую формулировку вопроса если она схожа по смыслу с уже существующими формулировками. Формулировка будет считаться схожей по смыслу если сервис уже определяет ее в базе знаний с точностью выше указанной. Установите 1, чтобы отключить проверку.
    • min_levenstein_distance - порог оценки близости ответов. Одинаковыми будут считаться ответы, отличающиеся друг от друга менее чем на указанное количество символов. Установите 0, чтобы отключить проверку.

    Детальнее
    Описание механизма защиты БЗ - autoFAQ how to

      Базы знаний - Общее
      Каждая база знаний содержит документы для одной целевой аудитории и/или тематики вопросов.

      База знаний содержит Документы в виде наборов "Название - Ответ - Вопросы к ответу". При обработке запроса сервис сравнивает смысл запроса с вопросами из документов в базе знаний, текст ответа в анализе участия не принимает. Детальнее - в разделе Как устроен autoFAQ.

      Вопросы хранятся в plain text виде, ответы - в plain text и html виде.

        Создать базу знаний
        Создание базы знаний и, опционально, наполнение документами. Возвращает service_id и service token.
          POST https://api.reason8.ai/v1/setup/create_service

          Content-Type: application/json
          Тело запроса
          {
              "user_id": user_id, # Идентификатор пользователя, integer, обязательно
              "user_token": user_token, # Токен пользователя, string, обязательно
              "name": "Новая база знаний", # Наименование БЗ, string, обязательно
              "preset": "ru", # Язык БЗ из ru / en, string, обязательно
              "trainable": True, # Признак автоматического дообучения БЗ, boolean, обязательно
              "max_trainable_score": 0.95, # Порог оценки близости вопросов для защиты БЗ при дообучении, float, опционально 
              "min_levenstein_distance": 1, # Порог оценки близости ответов для защиты БЗ при дообучении, float, опционально
              "ext": {  # Объект для хранения пользовательских данных, object, опционально
                  'answer_level': 0.6, # Порог точности для прямого ответа пользователям, float, опционально
                  'suggestion_level': 0.2 # Порог точности для подсказки операторам, float, опционально
              },
              "documents": [ # Список документов для наполнения БЗ при создании, array of objects, опционально
                  {
                      "name": "Новый документ №1", # Название документа, string, опционально
                      "question": "Новый вопрос", # Основной вопрос к документу, string, обязательно 
                      "answer": 'Новый ответ', # Ответ документа в plain text или html, string, обязательно 
                      'ext':{ # Объект для хранения пользовательских данных документа
                          'url':'http://link_to_file' # Пользовательские данные
                      },
                      "paraphrases": [ # Список альтернативных формулировок вопроса, array of objects, опционально
                          {
                              "text": 'Новый вопрос два', # Текст формулировки вопроса, string, обязательно
                              "author": '' # Служебное поле, string, обязательно
                          }
                      ]
                  }
              ]        
          }
          Тело ответа в случае HTTP status code = 200
          {
            "service_id": 1, # Идентификатор БЗ, integer
            "message": "Service created", # Сообщение, string
            "tokens": [ # Список токенов БЗ, array of strings
              "abc1324567980" # Токен БЗ, string
            ]
          }
          Тело ответа в случае HTTP status code > 200
          {
              'error': 1, # Признак ошибки, integer
              'message': 'invalid user_id' # Описание ошибки, string
          }

          Получить список баз знаний
          Создание базы знаний и, опционально, наполнение документами. Возвращает service_id и service token.
            GET https://api.reason8.ai/v1/setup/list_services?user_id=1&user_token=abcdef
            Параметры запроса
            user_id - идентификатор пользователя, integer, обязательно
            user_token - токен пользователя, string, обязательно
            Тело ответа в случае HTTP status code = 200
            [  # список баз знаний, array of objects
                {
                    'name': 'Новая база знаний', # Наименование БЗ, string
                    'service_id': 12345, # Идентификатор БЗ, string
                    'status': 'Serving', # Статус БЗ, string
                    'tokens': [ # Список токенов БЗ, array
                        'abcdefghiy' # Токен БЗ, string
                    ]
                }
            ]
            Тело ответа в случае HTTP status code > 200
            {
                'error': 1, # Признак ошибки, integer
                'message': 'invalid user_token' # Описание ошибки, string
            }

            Получить статус базы знаний
            Получение статуса базы знаний:
            Serving - база знаний отвечает на запросы, несохраненных изменений нет
            Unpublished- база знаний отвечает на запросы, есть несохраненные изменения
            Pending - БЗ в процессе публикации
            Stopped- база знаний не отвечает на запросы
              GET https://api.reason8.ai/v1/setup/get_service_status?user_id=1&user_token=abcdefgh&service_id=123456
              Параметры запроса
              user_id - идентификатор пользователя, integer, обязательно
              user_token - токен пользователя, string, обязательно
              service_id - идентификатор БЗ, integer, обязательно
              Тело ответа в случае HTTP status code = 200
              {
                  'message': "Service 'Новая база знаний' is Unpublished",
                  'status': 'Unpublished'
              }
              Тело ответа в случае HTTP status code > 200
              {
                  'error': 1, # Признак ошибки, integer
                  'message': 'No such service' # Описание ошибки, string
              }

              Получить содержание базы знаний
              Получение содержимого базы знаний, включая все документы, формулировки и настройки. Возвращает JSON объект.
                GET https://api.reason8.ai/v1/setup/get_service?user_id=1&user_token=abcdefgh&service_id=123456
                Параметры запроса
                user_id - идентификатор пользователя, integer, обязательно
                user_token - токен пользователя, string, обязательно
                service_id - идентификатор БЗ, integer, обязательно
                Тело ответа в случае HTTP status code = 200
                {
                    'documents': # Список документов, array of objects
                    [
                        {
                            'answer': 'Новый ответ', # Текст ответа документа, string
                            'document_id': 123456, # Уникальный идетнтификатор документа, integer
                            'ext': # Объект для хранения пользовательских данных документа, object
                            {
                                'url': 'http://link_to_file' # Хранимая в документе ссылка на приложенный файл
                            }, 
                            'name': 'Новый документ №1', # Наименование документа, string
                            'paraphrases':  # Список формулировок вопросов, array of objects
                            [
                                {
                                    'author': '', # Служебное поле, string
                                    'paraphrase_id': 456789, # Уникальный идентификатор формулировки, integer
                                    'text': 'Новый вопрос номер два' # Текст формулировки вопроса, string
                                }
                            ],
                            'question': 'Новый вопрос' # Текст основного вопроса к документу, string
                        }
                    ],
                    'ext':  # Поле для пользовательских данных и натсроек
                    {
                        'answer_level': 0.6,  # Хранимый в БЗ порог ответа пользователю
                        'suggestion_level': 0.2 # Хранимый в БЗ порог подсказки оператору        
                    },
                    'max_trainable_score': 0.95, # Порог оценки близости вопросов для защиты БЗ при дообучении, float
                    'min_levenstein_distance': 1, # Порог оценки близости ответов для защиты БЗ при дообучении
                    'name': 'Новая база знаний', # Наименование БЗ
                    'service_id': 123456, # Уникальный идентификатор БЗ
                    'status': 'Unpublished', # Статус БЗ
                    'tokens':  # Список токенов БЗ, array
                    [
                        '6b9aa93a0831421ea40ac0f6195ce539' # Токен БЗ, string
                    ],
                    'trainable': True # Признак автоматического дообучения БЗ, boolean
                }
                Тело ответа в случае HTTP status code > 200
                {
                    'error': 1, # Признак ошибки, integer
                    'message': 'invalid user_token' # Описание ошибки, string
                }

                Обновить базу знаний
                Обновить упомянутые в запросе параметры базы знаний. Пропущенные поля не изменяются, новые поля добавляются.
                  POST https://api.reason8.ai/v1/setup/update_service

                  Content-Type: application/json
                  Тело запроса
                  {
                      'user_id': user_id, # Уникальный идентификатор пользователя, integer, обязательно
                      'user_token': user_token, # Токен пользователя, string, обязательно
                      'service_id': service_id, # Уникальный идентификатор БЗ, integer, обязательно
                      'name': 'Новое название базы знаний', # Новое наименование БЗ, string, опционально
                      "ext": { # Поле для пользовательских данных и натсроек, object, опционально
                          "answer_level": 1.0 # Новое значение порога ответа, float, опционально
                      },
                      'trainable': False, # Новое значение признака автоматического дообучения, boolean, опционально 
                      'max_trainable_score': 0.95, # Новое значение порога оценки близости вопросов для защиты БЗ , float, опционально
                      'min_levenstein_distance': 3 # Новое значение порога оценки близости ответов для защиты БЗ, integer, опционально 
                  }
                  Тело ответа в случае HTTP status code = 200
                  {
                      'message': "Service updated"
                  }
                  Тело ответа в случае HTTP status code > 200
                  {
                      'error': 1, # Признак ошибки, integer
                      'message': 'invalid user_token' # Описание ошибки, string
                  }

                  Опубликовать базу знаний
                  Опубликовать изменения базы знаний.
                    GET https://api.reason8.ai/v1/setup/publish_service?user_id=1&user_token=abcdefgh&service_id=123456
                    Параметры запроса
                    user_id - идентификатор пользователя, integer, обязательно
                    user_token - токен пользователя, string, обязательно
                    service_id - идентификатор БЗ, integer, обязательно
                    Тело ответа в случае HTTP status code = 200
                    {
                        'message': "Service sent to publish"
                    }
                    Тело ответа в случае HTTP status code > 200
                    {
                        'error': 1, # Признак ошибки, integer
                        'message': 'invalid user_token' # Описание ошибки, string
                    }

                    Остановить базу знаний
                    Временно остановить работу БЗ. БЗ не будет отвечать на запросы, данные будут сохранены.
                      GET https://api.reason8.ai/v1/setup/stop_service?user_id=1&user_token=abcdefgh&service_id=123456
                      Параметры запроса
                      user_id - идентификатор пользователя, integer, обязательно
                      user_token - токен пользователя, string, обязательно
                      service_id - идентификатор БЗ, integer, обязательно
                      Тело ответа в случае HTTP status code = 200
                      {
                          'message': "Service stopped"
                      }
                      Тело ответа в случае HTTP status code > 200
                      {
                          'error': 1, # Признак ошибки, integer
                          'message': 'invalid user_token' # Описание ошибки, string
                      }

                      Удалить базу знаний
                      Удалить БЗ со всем содержимым без возможности восстановления.
                        GET https://api.reason8.ai/v1/setup/delete_service?user_id=1&user_token=abcdefgh&service_id=123456
                        Параметры запроса
                        user_id - идентификатор пользователя, integer, обязательно
                        user_token - токен пользователя, string, обязательно
                        service_id - идентификатор БЗ, integer, обязательно
                        Тело ответа в случае HTTP status code = 200
                        {
                            'message': "Service deleted"
                        }
                        Тело ответа в случае HTTP status code > 200
                        {
                            'error': 1, # Признак ошибки, integer
                            'message': 'invalid user_token' # Описание ошибки, string
                        }

                        Документы - Общее
                        При добавлении и обновлении документов запускается механизм защиты базы знаний - система вернет ошибку при попытке добавить близкий к существующим ответ или вопрос/формулировку вопроса. Степень близости регулируется параметрами защиты базы знаний.

                        Детальнее
                        Настройка параметров защиты БЗ через API - ошибки при работе с БЗ
                        Описание механизма защиты БЗ - autoFAQ how to

                          Добавить документ
                          Запрос добавляет 1 документ в базу знаний.
                            POST https://api.reason8.ai/v1/setup/create_document

                            Content-Type: application/json
                            Тело запроса
                            {
                                "user_id": user_id, # Уникальный идентификатор пользователя, integer, обязательно
                                "user_token": user_token, # Токен пользователя, string, обязательно
                                "service_id": service_id, # Уникальный идентификатор БЗ, integer, обязательно
                                "question": 'Новый вопрос', # Текст основного вопроса к документу, string, обязательно
                                "answer": 'Новый ответ', # Текст ответа документа, string, обязательно
                                'name':'Наименование', # Наименование документа, string, обязательно
                                'ext':  # Объект для хранения пользовательских данных документа, object, опционально
                                {
                                    'url':'http://link_to_file' # Хранимая в документе ссылка на приложенный файл
                                },  
                                "paraphrases":   # Список формулировок вопросов, array of objects, опционально
                                [
                                    {
                                         'author': '', # Служебное поле, string, обязательно
                                         'text': 'Новая формулировка вопроса' # Текст формулировки вопроса, string, обязательно
                                    }
                                ]
                            }
                            Тело ответа в случае HTTP status code = 200
                            {
                                'document_id': 123456,
                                'message': 'Document added',
                                'url': '/services/654321/documents/123456/edit'
                            }
                            Тело ответа в случае HTTP status code > 200
                            # Ошибка доступа к БЗ
                            {
                                'error': 1, # Признак ошибки, integer
                                'message': 'invalid user_token' # Описание ошибки, string
                            }
                            
                            # Ошибка - попытка добавить дублирующуюся формулировку
                            {
                                'error': 'similar_paraphrase',
                                'message': 'question rejected: top score is above max_trainable_score (1.000 > 0.950)',
                                'similar_document_id': 987654,
                                'similar_paraphrase': 'How are you',
                                'similar_paraphrase_id': -2
                            }
                            

                            Получить содержание документа
                            Запрос получает содержимое 1-го документа из базы знаний.
                              GET https://api.reason8.ai/v1/setup/get_document?user_id=123456&user_token=abcdefgh&service_id=123456&document_id=1654321
                              Параметры запроса
                              user_id - идентификатор пользователя, integer, обязательно
                              user_token - токен пользователя, string, обязательно
                              service_id - идентификатор БЗ, integer, обязательно
                              document_id - идентификатор документа, integer, обязательно
                              Тело ответа в случае HTTP status code = 200
                              {
                                  'answer': 'Новый ответ', # Текст ответа документа, string
                                  'document_id': 654321, # Уникальный идентификатор документа, integer
                                  'ext':  # Объект для хранения пользовательских данных документа, object
                                  {
                                      'url': 'http://link_to_file' # Хранимая в документе ссылка на приложенный файл
                                  },
                                  'name': 'Наименование', # Наименование документа, string
                                  'paraphrases':  # писок формулировок вопросов, array of objects
                                  [
                                      {
                                          'author': 'CLICK:TRAINABLE', # Служебное поле, string
                                          'paraphrase_id': 987654, # Уникальный идентификатор формулировки, integer
                                          'text': 'Новая формулировка 1' # Текст формулировки вопроса, string
                                      }
                                  ],
                                  'question': 'Новый вопрос' # Текст основного вопроса к документу, string
                              }
                              Тело ответа в случае HTTP status code > 200
                              {
                                  'error': 1, # Признак ошибки, integer
                                  'message': 'No such document' # Описание ошибки, string
                              }
                              
                              

                              Обновить документ
                              Запрос обновляет содержимое 1-го документа в базе знаний. Текст основного вопроса и ответа обязательны для указания и будут заменены. Список формулировок, наименование и пользовательский раздел - опциональны и будут заменены только в случае включения в запрос.
                                POST https://api.reason8.ai/v1/setup/update_document

                                Content-Type: application/json
                                Тело запроса
                                {
                                    "user_id": user_id, # Уникальный идентификатор пользователя, integer, обязательно
                                    "user_token": user_token, # Токен пользователя, string, обязательно
                                    "service_id": service_id, # Уникальный идентификатор БЗ, integer, обязательно
                                    "document_id": doc_id, # Уникальный идентификатор документа, integer, обязательно
                                    'question' : 'Новый вопрос', # Текст основного вопроса к документу, string, обязательно
                                    'answer' : 'Новый ответ', # Текст ответа документа, string, обязательно
                                    'ext': # Обновление параметров в пользовательском разделе, object, опционально
                                    {
                                        'url':'http://new_link_to_file', # Обновление пользовательского параметра, string
                                        'type':'message', # Добавление пользовательского параметра, string
                                    },
                                    'paraphrases':  # обновление списка формулировок вопросов, array of objects, опционально
                                    [
                                        { # Обновление формулировки, так как указан paraphrase_id
                                            'author': '', # Служебное поле, string
                                            'paraphrase_id': 987654, # Уникальный идентификатор формулировки, integer
                                            'text': 'Обновленная формулировка 1' # Замена текста формулировки на указанную, string
                                        },
                                        { # Добавление формулировки, без указания paraphrase_id
                                            'author': '', # Служебное поле, string
                                            'text': 'Новая формулировка' # Добавление новой формулировки вопроса, string
                                        }
                                    ]
                                }
                                Тело ответа в случае HTTP status code = 200
                                {
                                    'message': 'Document updated', # Текст сообщения, string
                                }
                                Тело ответа в случае HTTP status code > 200
                                # Ошибка доступа к документу
                                {
                                    'error': 1, # Признак ошибки, integer
                                    'message': 'No such document' # Описание ошибки, string
                                }
                                
                                # Ошибка - попытка добавить дублирующуюся формулировку
                                {
                                    'error': 'similar_paraphrase',
                                    'message': 'question rejected: top score is above max_trainable_score (1.000 > 0.950)',
                                    'similar_document_id': 987654,
                                    'similar_paraphrase': 'How are you',
                                    'similar_paraphrase_id': -2
                                }
                                

                                Удалить документ
                                Запрос удаляет документ со всем содержимым без возможности восстановления.
                                  GET https://api.reason8.ai/v1/setup/delete_document?user_id=123456&user_token=abcdefgh&service_id=123456&document_id=1987654
                                  Параметры запроса
                                  user_id - идентификатор пользователя, integer, обязательно
                                  user_token - токен пользователя, string, обязательно
                                  service_id - идентификатор БЗ, integer, обязательно
                                  document_id - идентификатор документа, integer, обязательно
                                  Тело ответа в случае HTTP status code = 200
                                  {
                                      'message': 'Document removed', # Текст сообщения, string
                                  }
                                  Тело ответа в случае HTTP status code > 200
                                  {
                                      'error': 1, # Признак ошибки, integer
                                      'message': 'No such document' # Описание ошибки, string
                                  }
                                  
                                  

                                  Отправить запрос
                                  Запрос анализирует входящее сообщение и возвращает топ 3 наиболее релевантных документов из БЗ, ориентируясь на смысловую близость сообщения и вопросов/формулировок в документах БЗ.

                                  Запрос всегда возвращает документы, вне зависимости от степени уверенности в ответе. Для каждого документа указывается свой уровень уверенности.

                                  Запрос может учитывать предыдущие сообщения, для этого указывается номер сессии, при отсутствии номера сессии интерпретируется как начало новой сессии.
                                    POST https://api.reason8.ai/v1/query

                                    Content-Type: application/json
                                    Тело запроса
                                    {
                                        "service_id": 123456, # Уникальный идентификатор БЗ, integer, обязательно 
                                        "service_token": 'abcdefgh', # Токен БЗ, string, обязательно
                                        'session_id': 'abdf3jad2', # Токен сессии, string, опционально
                                        "query": 'Вопрос к системе' # Текст соообщения, string, обязательно
                                    }
                                    Тело ответа в случае HTTP status code = 200
                                    {
                                        'query_id': '53a33e5adf4945edb25a43c17656f7a9', # Уникальный идентификатор запроса, string
                                        'results':  # Список результатов поиска в БЗ, array of objects
                                        [
                                            {
                                                'answer': 'What is your name', # Текст ответа найденного документа, string
                                                'document_id': 451137, #  Идентификатор найденного документа, integer
                                                'ext':  # Пользовательский раздел найденного документа, object
                                                {
                                                    'url': 'http://link_to_file'
                                                },
                                                'name': 'What is your name', # Наименование найденного документа, string
                                                'question': 'What is your name', # Основной вопрос найденного документа, string
                                                'score': 0.6287714243 # Уровень уверенности для найденного документа, float
                                            }
                                        ],
                                        'session_id': '3923a06ee2974ba5ab7f9b61ed048a05' # Уникальный идентификатор сессии, string
                                    }
                                    Тело ответа в случае HTTP status code > 200
                                    {
                                        'error': 1, # Признак ошибки, integer
                                        'message': 'No such service' # Описание ошибки, string
                                    }
                                    
                                    

                                    Отправить обратную связь
                                    Запрос обрабатывает обратную связь на результаты поиска по запросу query. Использование данного запроса необязательно, однако рекомендуется для дообучения базы знаний.

                                    На каждый запрос query может быть возвращен 1 запрос click с указанием на:
                                    • подтверждение найденного документа
                                    • текст ответа, взятый не из базы знаний (опционально, при наличии оператора, который может дать такой ответ)
                                    • оценка результатов поиска по 5-ти бальной шкале (опционально, при наличии механизма оценки результатов)

                                      Порядок указания параметров
                                        Для полностью автоматических подключений (без участия оператора) все вопросы к БЗ распределяются по следующим кейсам:
                                        • Вопрос решен автоматически
                                        • Вопрос остался без ответа

                                        Для отнесения к этим кейсам указывайте следующие параметры:
                                          Вопрос решен автоматически
                                          document_id = {номер корректного документа}
                                          suggested_answer = {пустая строка}
                                          Вопрос остался без ответа
                                          document_id = -1
                                          suggested_answer = {пустая строка}
                                          Для подключений БЗ в систему с участием операторов все вопросы к БЗ распределяются по следующим типам:
                                          1. Вопрос решен автоматически
                                          2. Вопрос решен оператором при помощи БЗ
                                          3. Вопрос решен оператором самостоятельно
                                          4. Вопрос остался без ответа

                                          Для отнесения к этим кейсам указывайте следующие параметры:
                                            Вопрос решен автоматически
                                            document_id = {номер корректного документа}
                                            suggested_answer = {пустая строка}
                                            Вопрос решен оператором при помощи БЗ
                                            document_id = {номер выбранного оператором документа}
                                            suggested_answer = {текст ответа оператора}
                                            Вопрос остался без ответа
                                            document_id = -1
                                            suggested_answer = {пустая строка}
                                            Вопрос решен оператором самостоятельно
                                            document_id = -1
                                            suggested_answer = {текст ответа оператора}
                                            POST https://api.reason8.ai/v1/click

                                            Content-Type: application/json
                                            Тело запроса
                                            {
                                                "service_id": 123456, # Идентификатор БЗ, string, обязательно
                                                "service_token": 'dafadad', # Токен БЗ, string, обязательно
                                                "query": 'Текст сообщения', # Текст сообщения из запроса, string, обязательно
                                                'query_id': 'afdwefw', # Идентификатор запроса, string, обязательно 
                                                'session_id': 'wefergewr', # Идентификатор сессии запроса, string, обязательно
                                                'document_id': 987654, # Обратная связь - указатель на выбранный документ, ineger, обязательно
                                                'suggested_answer': 'Ответ оператора' # Обратная связь - альтернативный ответ на вопрос, string, опционально
                                            }
                                            Тело ответа в случае HTTP status code = 200
                                            {
                                                'message': 'ОК', # Текст сообщения, string
                                            }
                                            Тело ответа в случае HTTP status code > 200
                                            {
                                                'error': 1, # Признак ошибки, integer
                                                'message': 'API handler error' # Описание ошибки, string
                                            }