HTTP API для тех, у кого своя площадка

Один POST-запрос на сообщение. Быстрые проверки отвечают сразу, вердикт нейросети догоняет вебхуком.

§1 Ключ и права

Ключ передаётся заголовком Authorization

Ключ создаётся в кабинете и показывается один раз. Дальше видно только префикс. Права выдаются по отдельности: ключ для проверки сообщений не обязан уметь читать тексты из логов.

Заголовок

Authorization: Bearer amk_live_...

moderate:write
Проверять сообщения
logs:read
Читать логи
logs:read_content
Читать тексты сообщений
policies:read
Читать политику
policies:write
Менять политику
preview:write
Пользоваться песочницей
keys:read
Смотреть ключи
keys:write
Создавать и отзывать ключи
queue:read
Смотреть очередь
queue:write
Разбирать очередь
feedback:write
Отправлять отметки об ошибках
appeals:write
Принимать апелляции
usage:read
Смотреть потребление
integrations:read
Смотреть подключённые площадки
integrations:write
Подключать и отключать площадки
webhooks:read
Смотреть подписки на события
webhooks:write
Заводить и отзывать подписки на события

§2 Проверка сообщения

Запрос и ответ на русском тексте

Синхронный ответ содержит решение быстрых проверок. Если случай спорный, в ответе будет промежуточное решение, а окончательное придёт вебхуком — обещать мгновенный вердикт нейросети мы не будем.

Запрос

curl -X POST https://api.automoderator.ru/v1/moderate \
  -H "Authorization: Bearer $AUTOMOD_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "0195...",
    "provider": "api",
    "text": "пр0даю акк c дeвaнoм за 500р",
    "author": { "external_id": "user-42", "display_name": "grief_1337" }
  }'

Ответ

{
  "decision": "delete",
  "violation": true,
  "top_category": "account_trade",
  "confidence": 0.94,
  "decided_by": "rules",
  "latency_ms": 4,
  "masked_text": "пр0даю акк c дeвaнoм за 500р"
}

§3 Вебхуки

Подпись, которую нужно проверять

Каждая доставка подписана HMAC-SHA256. Сверьте подпись до того, как доверять телу запроса, и отбрасывайте события старше пяти минут — так повторная отправка чужого запроса не пройдёт.

Заголовки доставки

webhook-id: msg_01H...
webhook-timestamp: 1789000000
webhook-signature: v1,V2hhdCBhIGxvdmVseSBkYXk...

подпись = base64(HMAC_SHA256(secret, "{id}.{timestamp}.{тело запроса}"))

§4 Справочник

58 маршрутов

Проверка сообщений

Главный вызов: отправляете текст, получаете решение.

POST/v1/moderatemoderate:write
POST/v1/moderate/batchmoderate:write

Логи и вердикты

История проверок, карточка события и переопределение решения.

GET/v1/verdictslogs:read
GET/v1/verdicts/{id}logs:read
POST/v1/verdicts/{id}/overridequeue:write

Политика

Черновики, публикация версий и проверка правил в песочнице.

GET/v1/policiespolicies:read
POST/v1/policiespolicies:write
DELETE/v1/policies/{id}policies:write
GET/v1/policies/{id}policies:read
PUT/v1/policies/{id}policies:write
POST/v1/policies/{id}/previewpreview:write
POST/v1/policies/{id}/publishpolicies:write
GET/v1/policies/{id}/settingspolicies:read
PUT/v1/policies/{id}/settingspolicies:write

Ключи

Создание, просмотр и отзыв ключей с отдельными правами.

GET/v1/keyskeys:read
POST/v1/keyskeys:write
DELETE/v1/keys/{id}keys:write
GET/v1/keys/{id}keys:read
PATCH/v1/keys/{id}keys:write

Очередь модерации

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

GET/v1/queuequeue:read
POST/v1/queue/{id}/claimqueue:write

Обратная связь

Отметка «это ошибка» — на ней калибруется точность.

GET/v1/feedbacklogs:read
POST/v1/feedbackfeedback:write

Апелляции

Обращения наказанных участников.

POST/v1/appealsappeals:write

Потребление

Сколько сообщений израсходовано и сколько осталось.

GET/v1/usageusage:read

Аккаунт

Регистрация, вход и текущая сессия кабинета.

POST/v1/auth/loginбез ключа
POST/v1/auth/logoutбез ключа
GET/v1/auth/meбез ключа
POST/v1/auth/registerбез ключа

Справочная информация

Список маршрутов, права и коды ошибок — то, из чего собрана эта страница.

GET/v1/metaбез ключа

Тарифы

Публичный каталог тарифов.

GET/v1/plansбез ключа

Служебные

Проверки живости и готовности для балансировщика.

GET/healthzбез ключа
GET/metricsбез ключа
GET/readyzбез ключа

Прочее

Маршруты, не попавшие в остальные разделы.

POST/v1/demoбез ключа
GET/v1/integrationsintegrations:read
POST/v1/integrationsintegrations:write
DELETE/v1/integrations/{id}integrations:write
PATCH/v1/integrations/{id}integrations:write
POST/v1/integrations/{id}/checkintegrations:write
GET/v1/learningpolicies:read
PATCH/v1/learningpolicies:write
POST/v1/learning/improvements/{id}policies:write
GET/v1/learning/reportpolicies:write
GET/v1/webhookswebhooks:read
POST/v1/webhookswebhooks:write
DELETE/v1/webhooks/{id}webhooks:write
GET/v1/webhooks/{id}/deliverieswebhooks:read
POST/v1/webhooks/{id}/rotatewebhooks:write
GET/v1/workspaceбез ключа
POST/v1/workspace/invitesбез ключа
DELETE/v1/workspace/invites/{id}без ключа
POST/v1/workspace/joinбез ключа
GET/v1/workspace/membersбез ключа
DELETE/v1/workspace/members/{id}без ключа
PATCH/v1/workspace/members/{id}без ключа
POST/v1/workspace/projectsбез ключа
POST/webhooks/telegram/{bot}без ключа

§5 Коды ошибок

Что вернётся, если что-то пошло не так

invalid_request400
invalid_json400
validation_failed422
unauthorized401
invalid_api_key401
invalid_credentials401
insufficient_scope403
forbidden403
not_found404
method_not_allowed405
conflict409
email_taken409
idempotency_key_reuse409
already_claimed409
lease_expired409
unsupported_media_type415
payload_too_large413
weak_password422
rate_limited429
quota_exhausted402
preview_quota_exhausted402
batch_not_allowed403
timeout504
service_unavailable503
internal_error500
policy_invalid422
scope_escalation403
content_unavailable403
unsupported_provider400

§6 Лимиты

Тело запроса: 1024 КБ
Сообщений в пачке: 100
Длина текста: 8192 символов
Размер страницы логов: 200

Остаток по частоте запросов приходит в заголовках RateLimit-Limit и RateLimit-Remaining.

Готовы попробовать на своём чате?

Быстрый старт Получить ключ