Обзор API

HTTP API нужен для внешних программ: получить записи, создать обращение, добавить комментарий или передать данные из другой системы. Программа действует с правами владельца ключа.

С чего начать

1. Определите действие: чтение, создание, изменение, событие или массовая загрузка.
2. Попросите администратора выдать отдельный ключ с минимальными правами.
3. Выполните первый запрос на чтение в тестовой среде.
4. Получите схему нужного типа. Поля вашей конфигурации могут отличаться от примеров.
5. Настройте обработку ошибок и повторов, затем переходите к записи.

Базовый адрес: https://YOUR_SERVER/api/v1. В документации используются только вымышленные домены и идентификаторы. Замените их адресом своего сервера. Для рабочего подключения используйте HTTPS.

Что входит в API

В справочнике описаны 56 операций: объекты, метаданные, жизненный цикл, связи, комментарии, файлы, SLA, база знаний, каталог, сотрудники, интеграции, импорт и экспорт.

Успешный JSON-ответ обычно имеет оболочку:

{
  "data": {},
  "meta": {"correlationId": "CORRELATION_ID", "apiVersion": "v1"}
}

Содержимое data зависит от метода: объект, массив или страница. Скачивание файла, экспорт и OpenAPI возвращают содержимое напрямую.

Границы возможностей

• Внутренние адреса браузерного интерфейса — не стабильный внешний API.
• Наличие действия в scope ключа не даёт доступа ко всем данным.
• Смена статуса выполняется через переход workflow, не произвольной записью поля статуса.
• OpenAPI доступен без ключа по /api/v1/openapi.json, но его схемы пока неполны. Используйте вместе со справочником и проверкой в тестовой среде.
• Не все административные сценарии полностью доступны извне. Например, аудиторию статьи базы знаний настраивают через интерфейс.

Связанные статьи

• Выбор способа интеграции
• Права доступа
• Термины