API

Основные коды состояния ответа HTTP

Локализация

Параметр {culture} отвечает за локализацию API, которая представляет собой код языка в соответствии со стандартом ISO 639-1.

Информационное сообщение

Вызовы некоторых методов возвращают только информационные сообщения. В этом случае код состояния ответа HTTP всегда будет 200, а возвращаемое сообщение будет выглядеть следующим образом:

{
  "message": "Операция успешно завершена"
}

где message - это сообщение от системы о результате выполнения какого-либо действия.

Сообщение об ошибке

Если что-то пойдет не так во время вызова метода или выполнения, код состояния ответа HTTP всегда будет отличаться от 200. В этом случае возвращаемое сообщение будет выглядеть следующим образом:

{
  "error": "Операция завершилась неудачей",
  "errorCode": 1234
}

где error — это сообщение от системы, содержащее причину ошибки, а errorCode — числовой код, позволяющий клиенту программно различать ошибки. Поле errorCode равно -1 для неклассифицированных ошибок и совпадает с номером ошибки БД для SQL-исключений.

Коды ошибок

Коды сгруппированы по областям: 1xxx - аутентификация и учетная запись, 2xxx - проверка на заимствования, 3xxx - поисковый индекс, 4xxx - создание B2B-пользователя, 5xxx - права доступа, 6xxx - сервисы.

Аутентификация/Авторизация

Получение токена

POST /{culture}/api/issue-access-token

метод позволяет получить токен для последующей аутентификации и авторизации в системе.

Content-Type: application/json

Запрос:

{
  "username": "user@example.com",
  "password": "64e09891d828"
}

В случае успешного выполнения ответ будет выглядеть следующим образом:

{
  "expiration": "2077-01-01T00:00:00Z",
  "token": "..."
}

где expiration — срок действия токена, а token — сам токен.

Заголовок HTTP-аутентификации/авторизации

Токен, полученный на первом шаге, должен использоваться во всех перечисленных ниже методах API путем добавления заголовка Authorization со значением Bearer <Token>.

Пример заголовка в HTTP-запросе:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

где eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9 это полученный токен.

Перевыпуск токена

GET /{culture}/api/refresh-access-token

метод позволяет обновить токен аутентификации и авторизации в системе.

Authorization: Bearer <Token>

В случае успешного выполнения ответ будет выглядеть следующим образом:

{
  "expiration": "2077-01-01T00:00:00Z",
  "token": "..."
}

где expiration — срок действия токена, а token — сам токен.

Основная информация

Получение оргструктур

GET /{culture}/api/user-structures

метод получает полную иерархию организационных структур.

Authorization: Bearer <Token>

В случае успешного выполнения ответ будет выглядеть следующим образом:

{
    "name": null,
    "id": 0,
    "childNodes": [
        {
            "name": "...",
            "id": 1,
            "childNodes": []
        }
    ]
}

Получение папок пользователя

GET /{culture}/api/user-folders

метод получает полную иерархию папок пользователя.

Authorization: Bearer <Token>

В случае успешного выполнения ответ будет выглядеть следующим образом:

{
    "name": null,
    "id": 0,
    "childNodes": [
        {
            "name": "...",
            "id": 1,
            "childNodes": []
        }
    ]
}

B2B-пользователи

Создание B2B-пользователя

POST /{culture}/api/create-b2b-user

метод позволяет аутентифицированному B2B-менеджеру или модератору программно создать и привязать нового пользователя к своей организации. Email пользователя всегда подтверждается автоматически. Если пароль указан, он устанавливается при создании; иначе на email пользователя отправляется ссылка на установку пароля.

Authorization: Bearer <Token> Content-Type: application/json

Запрос:

{
  "username": "user@example.com",
  "firstName": "Ivan",
  "lastName": "Ivanov",
  "description": "...",
  "role": 3,
  "nodeId": 1234,
  "password": "P@ssw0rd!",
  "dailyLimit": 10,
  "subscriptionLimit": 100
}

В случае успешного выполнения ответ будет выглядеть следующим образом:

{
  "userId": 1234,
  "username": "user@example.com",
  "subscriberId": 42,
  "isNewUser": true,
  "passwordSet": true,
  "passwordResetEmailSent": false,
  "message": "Пользователь создан и привязан к B2B-организации"
}

При ошибке ответ возвращается в стандартном формате API { "error": ..., "errorCode": ... }. Значения errorCode, специфичные для этого метода:

Поисковый индекс

Добавление документа в поисковый индекс

PUT /{culture}/api/add-to-search-index

метод позволяет добавить документ в поисковый индекс, который закреплен за пользователем или его организацией.

Authorization: Bearer <Token> Content-Type: application/json

Запрос:

{
  "filename": "example.txt",
  "title": "Pacifica`s Braindances",
  "author": "Victor Vector, Dakota Smith",
  "year": 2024,
  "url": "https://example.com/doc/9fe76511d0ee",
  "body": "0YHRitC10YjRjCDQttC1INC10YnRkSDRjdGC0LjRhSDQvNGP
  0LPQutC40YUg0YTRgNCw0L3RhtGD0LfRgdC60LjRhSDQsdGD0
  LvQvtC6LCDQtNCwINCy0YvQv9C10Lkg0YfQsNGO"
}

В случае успешного выполнения ответ будет выглядеть следующим образом:

{
  "message": "Документ добавлен в поисковый индекс"
}

Удаление документа из поискового индекса

DELETE /{culture}/api/remove-from-search-index

метод позволяет удалить документ из поискового индекса, закрепленного за пользователем или его организацией.

Authorization: Bearer <Token> Content-Type: application/json

Запрос:

{
  "url": "https://example.com/doc/9fe76511d0ee"
}

где url - это URL документа в поисковом индексе.

В случае успешного выполнения ответ будет выглядеть следующим образом:

{
  "message": "Документ удален из поискового индекса"
}

Массовые операции с поисковым индексом

/{culture}/api/remove-from-search-index?refresh=false

/{culture}/api/add-to-search-index?refresh=false

Для массового добавления или удаления документов необходимо использовать вышеперечисленные методы с параметром refresh и установленным значением в false. Чтобы применить изменения после массовых операций, нужно вызвать метод обновления индекса /{culture}/api/refresh-search-index.

Обновление поискового индекса

GET /{culture}/api/refresh-search-index

метод позволяет обновить поисковый индекс, закрепленный за пользователем или его организацией.

Authorization: Bearer <Token>

В случае успешного выполнения ответ будет выглядеть следующим образом:

{
  "message": "Поисковый индекс обновлен"
}

Очистка поискового индекса

GET /{culture}/api/clear-search-index

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

Authorization: Bearer <Token>

В случае успешного выполнения ответ будет выглядеть следующим образом:

{
  "message": "Поисковый индекс очищен"
}

Проверка на плагиат

Отправка документа на проверку

POST /{culture}/api/plagiarism-check

метод позволяет отправить документ на проверку в систему обнаружения заимствований.

Authorization: Bearer <Token> Content-Type: application/json

Запрос:

{
  "structureId": 1000,
  "folderId": 1,
  "filename": "example.txt",
  "author": "Anders Helman, Brandon Frost",
  "year": 2024,
  "body": "0YHRitC10YjRjCDQttC1INC10YnRkSDRjdGC0LjRhSDQvNGP
  0LPQutC40YUg0YTRgNCw0L3RhtGD0LfRgdC60LjRhSDQsdGD0
  LvQvtC6LCDQtNCwINCy0YvQv9C10Lkg0YfQsNGO",
  "disableDuplicateChecking": false
}

В случае успешного выполнения ответ будет выглядеть следующим образом:

{
  "id": 1000,
  "state": 2
}

где id - это идентификатор проверки, а state - текущее состояние проверки.

При обнаружении дубликата (state = 1) ответ также будет содержать идентификатор исходной проверки:

{
  "id": 1001,
  "state": 1,
  "duplicateOf": 1000
}

где duplicateOf — идентификатор исходной проверки, результаты которой можно получить. Поле duplicateOf присутствует только при state = 1 и отсутствует в остальных случаях.

Получение состояния проверки

GET /{culture}/api/plagiarism-check-se/{id}

метод позволяет получить текущее состояние проверки.

Authorization: Bearer <Token>

В случае успешного выполнения ответ будет выглядеть следующим образом:

{
  "id": 1000,
  "state": 2
}

где id - это идентификатор проверки, а state - текущее состояние проверки.

Статус доступен только для проверок, к которым у вас есть доступ, иначе возвращается ошибка 5000.

Управление результатом проверки

GET DELETE /{culture}/api/plagiarism-check-rs/{id}

метод позволяет получить или удалить результат проверки.

Authorization: Bearer <Token>

Если операция успешно выполнена при вызове метода GET, ответное сообщение будет выглядеть следующим образом:

{
    "isContainsDeception": false,
    "hasAi": true,
    "hasForeignAgent": false,
    "metrics": {
      "originality": 0.0,
      "citation": 0.0,
      "bibliography": 0.0,
      "match": 1.0,
      "ai": 0.37
    },
    "sources": [
        {
          "metrics": {
             "citation": 0.0,
             "match": 1.0
          },
          "url": "https://www.example.org/abcd/1970.00001",
          "title": null,
          "author": null,
          "year": null
        },
        ...
    ]
}

Значения по ИИ и иноагентам учитывают правки проверяющего в средстве просмотра отчета; там же - подробности, ссылки на средство просмотра описаны ниже.

Если проверка завершилась неудачей, метод возвращает сообщение об ошибке.

Подробный отчет в формате PDF

GET /{culture}/api/plagiarism-check-rp/{id}/extended

метод позволяет получить расширенный отчет о проверке в формате PDF.

Authorization: Bearer <Token>

Примеры:

/{culture}/api/plagiarism-check-rp/{id}/extended?utc=300
/{culture}/api/plagiarism-check-rp/{id}/extended?utc=-600

Возвращает файл формата PDF с заголовком HTTP content-type: application/pdf.

Краткий отчет в формате PDF

GET /{culture}/api/plagiarism-check-rp/{id}/summary

метод позволяет получить краткий отчет о проверке в формате PDF. Если вы хотите включить в отчет оригинальный документ, просто добавьте ?withOriginal=true.

Authorization: Bearer <Token>

Примеры:

/{culture}/api/plagiarism-check-rp/{id}/summary?utc=300
/{culture}/api/plagiarism-check-rp/{id}/summary?utc=-600&withOriginal=true

Возвращает файл формата PDF с заголовком HTTP content-type: application/pdf.

Справка в формате PDF

GET /{culture}/api/plagiarism-check-rp/{id}/reference

метод позволяет получить справку в формате PDF.

Authorization: Bearer <Token>

Примеры:

/{culture}/api/plagiarism-check-rp/{id}/reference?utc=300
/{culture}/api/plagiarism-check-rp/{id}/reference?utc=-600

Возвращает файл формата PDF с заголовком HTTP content-type: application/pdf.

Интерактивный просмотр отчета

Постоянная ссылка на средство просмотра отчета [editable]

GET /{culture}/api/permanent-viewer/{id}

метод возвращает постоянную ссылку для открытия средства просмотра отчета.

Authorization: Bearer <Token>

В случае успешного выполнения ответ будет выглядеть следующим образом:

{
  "permanent-link": "https://example.com/document/[\d]"
}

где permanent-link - это бессрочная ссылка на средство просмотра отчетов.

Одноразовая ссылка на средство просмотра отчета [readonly]

GET /{culture}/api/one-time-viewer/{id}

метод возвращает одноразовую ссылку для открытия средства просмотра отчета.

Authorization: Bearer <Token>

В случае успешного выполнения ответ будет выглядеть следующим образом:

{
  "one-time-link": "https://example.com/document/[\d]",
  "expires": "2024-03-21T20:17:00.0903957Z"    
}

где one-time-link - это одноразовая ссылка на средство просмотра отчета, а expires - дата и время истечения срока действия ссылки

Сервисы

Сервисы ниже - те же, что работают внутри проверки на заимствования, но доступны по отдельности. Проверка библиографии и определение ИИ требуют соответствующих опций тарифа.

Извлечение текста из документа

POST /{culture}/api/document-text

метод извлекает текст документа постранично. OCR применяется, если включен в тарифе.

Authorization: Bearer <Token> Content-Type: application/json

Запрос:

{
  "filename": "example.pdf",
  "body": "JVBERi0xLjcKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFsb2c..."
}

В случае успешного выполнения ответ будет выглядеть следующим образом:

{
  "pages": [
    "...",
    "..."
  ]
}

Извлечение библиографии

POST /{culture}/api/bibliography

метод находит библиографические ссылки в текстах страниц, например полученных методом извлечения текста, и возвращает их тексты в порядке появления.

Authorization: Bearer <Token> Content-Type: application/json

Запрос:

{
  "pages": [
    "...",
    "..."
  ]
}

В случае успешного выполнения ответ будет выглядеть следующим образом:

[
  "Smith J. Braindances of Pacifica. 2024. P. 12-19.",
  "..."
]

Проверка библиографии

POST /{culture}/api/bibliography-check

метод запускает проверку ссылок, например полученных предыдущим методом, и возвращает идентификатор задачи. Проверка занимает время, поэтому результат получается отдельным запросом.

Authorization: Bearer <Token> Content-Type: application/json

Запрос:

{
  "references": [
    "Smith J. Braindances of Pacifica. 2024. P. 12-19.",
    "..."
  ]
}

В случае успешного выполнения ответ будет выглядеть следующим образом:

{
  "taskId": "9c1f0f2e-7c1a-4d1e-9b0a-2f1c9d8e7a65"
}

Получение результата проверки

GET /{culture}/api/bibliography-check/{taskId}

метод возвращает состояние задачи проверки и, когда она завершена, вердикты в порядке ссылок.

Authorization: Bearer <Token>

Пока задача выполняется, ответ выглядит так:

{
  "status": "processing"
}

Когда задача завершена:

{
  "status": "done",
  "verdicts": [
    {
      "status": 1,
      "reason": null,
      "doi": "10.1000/xyz123",
      "sourceUrl": "https://example.com/article/xyz123",
      "registries": [
        {
          "name": "crossref",
          "url": "https://api.crossref.org/works/10.1000/xyz123"
        }
      ],
      "normalized": "smith j braindances of pacifica 2024",
      "fields": {
        "doi": 1,
        "year": 1,
        "title": 1
      }
    }
  ]
}

Поля вердикта:

Коды вердикта в status:

Коды совпадения в fields:

Проверка текста на генерацию ИИ

POST /{culture}/api/ai-check

метод делит тексты страниц на предложения так же, как проверка на заимствования, и возвращает вероятность генерации ИИ для каждого предложения и для непрерывных блоков.

Authorization: Bearer <Token> Content-Type: application/json

Запрос:

{
  "pages": [
    "...",
    "..."
  ]
}

В случае успешного выполнения ответ будет выглядеть следующим образом:

{
  "sentences": [
    {
      "id": 0,
      "page": 0,
      "value": "...",
      "length": 96,
      "wordCount": 14,
      "probability": 0.93,
      "isGenerated": true,
      "blockId": 0,
      "excluded": false
    }
  ],
  "blocks": [
    {
      "id": 0,
      "sentenceStartId": 0,
      "sentenceEndId": 4,
      "fakeProbability": 0.91,
      "isGenerated": true,
      "tokenCount": 140,
      "wordCount": 120,
      "excluded": false
    }
  ]
}

Поля предложения, те же, что в результате проверки на заимствования:

Поля блока: