📡 REST API

REST API предназначен для интеграции ваших систем с платформой Fixorix по HTTPS.

Публичное API устроено как шлюз: он принимает ваш запрос, проверяет API-ключ и его права, сам подставляет идентификатор проекта и передаёт запрос во внутренний сервис Fixorix, возвращая ответ без изменений.

Базовый адрес: https://api.fixorix.ru Версии: сейчас доступна только v1 — все публичные пути начинаются с /v1/.

Обращение к неизвестному пути или к неподдерживаемому методу возвращает 404 Not Found — даже раньше, чем проверяется ключ.

🔎 Где смотреть актуальную спецификацию

👉 Swagger UI: https://api.fixorix.ru/swagger-ui

Открыть его можно и прямо из интерфейса: Настройки проекта → вкладка «API» → кнопка «Swagger UI» (справа вверху, рядом с «Создать ключ»).

Что важно знать про эту спецификацию:

Она собирается на лету из спецификаций внутренних сервисов, но содержит только опубликованные операции — то, что реально доступно по API-ключу.
В описании каждой операции есть блок обязательных прав (Required scopes).
Разделы сгруппированы по системам. Четыре из них переименованы для читаемости — Bots, Users, Messages, Knowledge Base; остальные сохраняют исходные названия своих сервисов.
Внутренний параметр projectId из операций вырезан — проект определяется по вашему ключу.
Авторизация показана как Bearer-ключ, поэтому в Swagger UI работает «Try it out» с вашим собственным ключом.
Спецификация кэшируется около 5 минут — только что изменившийся набор операций появится в ней с небольшой задержкой.

Коротко

Набор публичных маршрутов расширяется, и Swagger UI — единственный источник, который всегда ему соответствует. Эта страница описывает общие правила: ключи, права, лимиты, формат ошибок и параметры запросов.

📦 Что покрывает API

Сейчас наружу опубликовано 244 маршрута и 52 права доступа (scopes). Маршруты разложены по разделам:

Раздел	Префикс путей	Группа прав
Боты и каналы	`/v1/bots/…`	`BOTS_*`
Участники и роли	`/v1/person-profile/…`	`USERS_*`
Сообщения	`/v1/messages/…`, `/v1/message/…`	`MESSAGES_*`
База знаний	`/v1/knowledge-base/…`	`KNOWLEDGE_BASE_*`
AI	`/v1/ai/…`	`AI_*`
Сценарии и их запуски	`/v1/flows/…`, `/v1/flow/executions/…`	`FLOWS_*`
Метрики и дашборды	`/v1/metrics/…`	`METRICS_*`
Настройки проекта	`/v1/settings/…`	`SETTINGS_*`
Короткие ссылки	`/v1/short-link/…`, `/v1/shortener/…`	`SHORT_LINKS_*`
Хранилище файлов	`/v1/storage/…`	`STORAGE_*`
Теги	`/v1/tags/…`	`TAGS_*`
Обращения (техподдержка)	`/v1/tech-support/…`	`TECH_SUPPORT_*`
Виджеты	`/v1/widget/…`	`WIDGETS_*`
Служебное	`/v1/ping`	не проверяются

Точный список — в Swagger UI

Таблица показывает разделы и группы прав, а не полные адреса методов. Какие именно операции опубликованы в каждом разделе и какие права требует конкретный метод — написано в Swagger UI, в описании операции (блок Required scopes). Соответствие раздела и группы прав — по названию.

Тикетов в публичном API нет

Среди опубликованных разделов нет тикетов: создавать, читать и менять тикеты по API-ключу нельзя. Тикеты ведутся в интерфейсе — см. Система тикетов.

Подробное описание работы с базой знаний — на странице База знаний в API. Полный разбор прав — на странице Scopes.

🔐 API-ключи

Экран «API-ключи»

API-ключи создаются и управляются в интерфейсе Fixorix: Настройки проекта → вкладка «API». Заголовок экрана — «API-ключи», подпись — «Управление ключами Public API проекта».

На экране — таблица ключей:

Колонка	Что показывает
Имя	Имя ключа и его описание
Права	Отметки о выданных scope-ах
Статус	«Активен», «Отозван» или «Истёк»
Автор	Участник, создавший ключ
Создан	Дата и время создания
Использован	Дата и время последнего успешного вызова API или «Никогда»
Истекает	Дата окончания или «Бессрочный»
Действия	Редактирование и отзыв ключа

Список можно сортировать по колонкам «Имя» и «Создан». Если ключей ещё нет, экран показывает «Пока нет API-ключей».

Нужна роль администратора

Создавать, просматривать, изменять и отзывать ключи может только участник с ролью «Администратор» или «Владелец». Вкладка «API» видна всем участникам проекта, но при нехватке прав вместо списка появится сообщение: «Не удалось загрузить ключи. Возможно, недостаточно прав — нужна роль администратора проекта.»

📷 Скриншот: экран «API-ключи» с таблицей ключей и кнопками «Создать ключ» и «Swagger UI» (будет добавлен).

Как создать ключ

Откройте проект → Настройки → вкладка «API».
Нажмите «Создать ключ» — откроется окно «Создание API-ключа».
Заполните поля и отметьте нужные права.
Нажмите «Создать ключ» в окне.
Скопируйте секрет из окна «Ключ создан».

Поля окна:

Поле	Обязательно	Описание
Имя	да	Понятное название, например `ci-pipeline-key`. Длина — от 1 до 255 символов. Без имени форма покажет «Укажите имя ключа»
Описание	нет	Свободный комментарий
Срок действия	нет	Дата; должна быть в будущем. Подсказка — «Оставьте пустым для бессрочного ключа»
Права доступа (scopes)	да	Матрица «ресурс × действие». Нужно отметить хотя бы один пункт, иначе — «Выберите хотя бы один scope»

Про выбор прав подробно — на странице Scopes.

Секрет ключа

Секрет выглядит как fxr_ и 43 случайных символа, например fxr_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.

В окне «Ключ создан» есть кнопка «Копировать» и предупреждение: «Скопируйте секрет сейчас — он показывается единственный раз и больше не будет доступен.»

Секрет показывается один раз

На сервере хранится только необратимый хеш секрета. Восстановить потерянный секрет невозможно — придётся создать новый ключ и отозвать старый.

Редактирование и отзыв ключа

Редактирование — кнопка в строке таблицы, окно «Редактирование API-ключа», кнопка «Сохранить». Изменить можно только имя и описание.
Отзыв — кнопка в строке таблицы, окно «Отзыв ключа»: «После отзыва ключ перестанет работать. Действие необратимо.», кнопка «Отозвать». Отозванный ключ остаётся в списке со статусом «Отозван», повторно отозвать его нельзя.

Правила безопасности

Ключ привязан к одному проекту — запросы выполняются в его контексте.
Храните секрет как пароль: в переменных окружения или хранилище секретов.
Не используйте ключ в клиентских приложениях (frontend, мобильные приложения).
Выдавайте минимально необходимые права.
Периодически проверяйте колонку «Использован»: ключи, которые давно не вызывались, стоит отозвать.

Ограничения

Ограничение	Что это значит на практике
Права выпущенного ключа не меняются	Чтобы добавить или убрать право, ключ нужно отозвать и выпустить новый — новый секрет придётся прописать во всех интеграциях
Срок действия не меняется	Продлить ключ нельзя; заранее следите за колонкой «Истекает» и выпускайте новый до этой даты
Ротации секрета нет	Операции «перевыпустить секрет, сохранив ключ» не существует. Смена секрета — это всегда новый ключ и отзыв старого
Лимит запросов одинаков для всех	1000 запросов в минуту на ключ; настроить лимит под конкретный ключ, интеграцию или тариф нельзя
Один ключ — один проект	Ключ работает только в том проекте, где выпущен. Для второго проекта нужен свой ключ

Коротко

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

🩺 Проверка ключа

Прежде чем отлаживать интеграцию, убедитесь, что ключ живой и шлюз отвечает:

curl -i -X GET \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  https://api.fixorix.ru/v1/ping

Успешный ответ — 200 с пустым телом и заголовком X-Request-Id.
Права (scopes) для ping не проверяются — важна только валидность самого ключа.
Вызов обновляет отметку «Использован» у ключа и расходует одну единицу лимита запросов.

✅ Как делать запросы

Заголовки

Заголовок	Назначение
`Authorization: Bearer <YOUR_API_KEY>`	Обязателен для всех запросов, включая `/v1/ping`
`Accept: application/json`	Ожидаемый формат ответа
`Content-Type: application/json`	Для методов с телом запроса
`X-Request-Id: <ваш идентификатор>`	Необязателен. Если не передать — шлюз сгенерирует свой. Этот идентификатор попадает в логи, его удобно называть при обращении в поддержку

Ваши заголовки Authorization и Host во внутренние сервисы не передаются — шлюз подставляет служебные.

Пример запроса

curl -X GET \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Accept: application/json" \
  https://api.fixorix.ru/v1/ping

Остальные вызовы устроены так же — меняются путь, метод и тело. Точные адреса берите в Swagger UI: там же запрос можно выполнить кнопкой «Try it out» и увидеть готовую команду curl.

📄 Параметры, пагинация и сортировка

Точный набор параметров каждого метода смотрите в Swagger UI. Общие правила такие:

Параметр	По умолчанию	Что делает
`page`	`0`	Номер страницы, нумерация с нуля
`size`	`20`	Размер страницы у постраничных методов
`sort`	зависит от метода	Поле и направление, например `sort=createdAt,desc`

Постраничные не все методы: часть возвращает полный список и параметров страницы не принимает.
У поиска по базе знаний порядок результатов фиксированный — от новых документов к старым, задать сортировку нельзя.

⏱ Лимиты запросов

1000 запросов в минуту на каждый API-ключ. Лимит считается по ключу, а не по проекту: у двух ключей одного проекта — по 1000 запросов в минуту каждый.
Окно — календарная минута: счётчик обнуляется в начале следующей минуты.
При превышении возвращается 429 Too Many Requests с телом Rate limit exceeded и заголовками:
- Retry-After: <секунд> — сколько секунд осталось до начала следующей минуты;
- X-RateLimit-Limit: <лимит> — действующий лимит.

Лимит не настраивается

1000 запросов в минуту — единое значение для всех ключей и всех проектов. Поднять его для отдельного ключа, интеграции или тарифа нельзя.

Временное отключение лимита

При недоступности подсистемы лимитов запросы пропускаются без подсчёта — на клиенте это никак не проявляется.

❗ Формат ошибок

Ошибки самого шлюза возвращаются обычным текстом (не JSON): корректный HTTP-статус и одна строка с описанием.

Статус	Тело ответа	Когда возникает
`401`	`Missing or invalid Authorization header`	Нет заголовка `Authorization` или он не начинается с `Bearer`
`401`	`Invalid API key`	Такого ключа не существует
`401`	`API key is not active`	Ключ отозван
`401`	`API key has expired`	Истёк срок действия ключа
`401`	`API key has no scopes`	У ключа не выдано ни одного права
`403`	`Insufficient scopes for this operation`	Ключу не хватает прав для этого метода
`404`	`Not Found`	Неизвестный путь или метод
`429`	`Rate limit exceeded`	Превышен лимит запросов
`502`	`Bad Gateway`	Шлюз не смог соединиться с внутренним сервисом
`504`	`Gateway Timeout`	Внутренний сервис не ответил за 30 секунд

Ошибки внутренних сервисов (400, 403, 404, 409, 422, 500 и т. д.) проксируются клиенту как есть — их формат определяет соответствующий сервис Fixorix. Например, ошибки валидации тела запроса приходят именно оттуда: сам шлюз тело не проверяет.

Идентификатор запроса передаётся заголовком X-Request-Id, а не в теле ответа.

Порядок проверок

Шлюз проверяет запрос в такой последовательности:

Подбирает маршрут по методу и пути — если маршрута нет, сразу 404 (ещё до проверки ключа).
Читает Authorization: Bearer … — иначе 401.
Находит ключ по секрету — иначе 401.
Проверяет, что ключ активен, не истёк и у него есть хотя бы одно право — иначе 401.
Проверяет права, требуемые маршрутом — иначе 403.
Проверяет лимит запросов — иначе 429.
Передаёт запрос во внутренний сервис и возвращает его ответ.

Поэтому запрос с неверным ключом на несуществующий путь вернёт 404, а не 401.

🧪 Диагностика частых случаев

Симптом	Причина и решение
`404 Not Found` на, казалось бы, существующий метод	Публично опубликован ограниченный список маршрутов, всё остальное отдаёт `404`. Сверьте путь и HTTP-метод со Swagger UI
`401 Unauthorized`	Проверьте заголовок `Authorization: Bearer <ключ>` — секрет начинается с `fxr_`. Посмотрите статус ключа на экране «API-ключи»: «Отозван» и «Истёк» дают `401`. Ключ без единого выданного права тоже даёт `401`
`403 Forbidden`	Ключу не хватает прав для этого метода. Требуемые права указаны в описании операции в Swagger UI (блок Required scopes). Изменить права у существующего ключа нельзя — выпустите новый и отзовите старый
`429 Too Many Requests`	Используйте заголовок `Retry-After` и повторяйте запрос с задержкой. Если лимита систематически не хватает, распределите нагрузку между несколькими ключами — лимит считается на ключ
`502` или `504`	Проблема на стороне Fixorix: шлюз не достучался до внутреннего сервиса или тот не ответил за 30 секунд. Повторите запрос позже; при повторении сообщите в поддержку значение `X-Request-Id`

Кто что может

Действие	Минимальная роль
Открыть вкладку «API»	Участник проекта
Посмотреть список ключей	Администратор
Создать ключ	Администратор
Изменить имя и описание ключа	Администратор
Отозвать ключ	Администратор
Вызывать методы API по выпущенному ключу	Роль не проверяется — важны только права самого ключа

Нужна помощь?

Если запрос стабильно возвращает 502, 504 или неожиданный ответ, напишите в поддержку и приложите значение заголовка X-Request-Id — по нему запрос находится в логах.

Scopes · База знаний в API · Webhooks · API Fixorix

🔎 Где смотреть актуальную спецификацию​

📦 Что покрывает API​

🔐 API-ключи​

Экран «API-ключи»​

Как создать ключ​

Секрет ключа​

Редактирование и отзыв ключа​

Правила безопасности​

Ограничения​

🩺 Проверка ключа​

✅ Как делать запросы​

Заголовки​

Пример запроса​

📄 Параметры, пагинация и сортировка​

⏱ Лимиты запросов​

❗ Формат ошибок​

Порядок проверок​

🧪 Диагностика частых случаев​

Кто что может​