Moderation API

moderation api the moderation api lets you protect a bot from abusive traffic by managing ip level bans from your own backend this functionality is intended for moderation and trust and safety workflows by integrating these endpoints into your admin tools, you can ban the visitor behind a specific chat, lift bans your operators have issued, and audit which bans are actively rejecting traffic all without giving operators direct access to the kindly dashboard getting started the moderation api uses the same authentication as the application api, so if you've already set up an application for your bot you're ready to go — skip ahead to authorization below if not, follow the steps under application api docid\ cgad bxmm1 wvggzsmd1k first to create your application and obtain an api key enable ip banning on your bot before any of the moderation api endpoints will respond, the bot itself must have ip banning turned on from the dashboard of your kindly bot, go to settings → privacy & security toggle ip banning on save your changes with the flag on, the chatbubble starts recording the ip address of each visitor against their chat the ban endpoint uses this history to resolve a chat id to the ip it should block, so bans issued before the flag was enabled may not have an ip to act on if the feature is off, every moderation api endpoint rejects with 400 ip ban enabled is off for this bot authorization with the api key in hand, you're ready to start issuing bans every request should include the header authorization bearer {{api key}} b an to ban the visitor behind a chat your service can post to api/v2/ban the api resolves the chat's last seen ip address and creates (or refreshes) a ban keyed on {bot id, ip address}, so re banning the same ip reuses the existing row example post to kindly curl request post \\ \ url https //bot kindly ai/api/v2/ban \\ \ header 'content type application/json' \\ \ header 'authorization bearer your api key' \\ \ data '{ "chat id" "\<chat id>", "reason" "spam", "banned by agent id" "\<agent id>", "expires at" "2026 06 01t00 00 00 000z" }' response { "id" "\<ban id>", "chat id" "\<chat id>", "ip address" "\<ip address>", "reason" "spam", "banned by agent id" "\<agent id>", "banned at" "2026 05 14t08 30 00 000z", "expires at" "2026 06 01t00 00 00 000z" } returns 400 cannot ban this chat no ip recorded if the chat has had no activity in the last 24 hours — ban a chat that has recent traffic unban to lift a ban your service can post to api/v2/unban with the chat id the ban was created from the api first resolves the chat's last seen ip and deletes the ban by ip; if that lookup fails it falls back to the legacy {bot id, chat id} tag, so unban remains idempotent even if the chat or its ip history is no longer available example post to kindly curl request post \\ \ url https //bot kindly ai/api/v2/unban \\ \ header 'content type application/json' \\ \ header 'authorization bearer your api key' \\ \ data '{ "chat id" "\<chat id>" }' response { "chat id" "\<chat id>", "unbanned" { "ip address" "\<ip address>" } } if no active ban matched the chat, unbanned is null and the response is still 200 — calling unban repeatedly is safe list bans to list every active ban for a bot your service can get api/v2/chat bans expired bans are filtered out server side and results are sorted by banned at descending each entry includes blocked count (how many requests the ban has rejected) and unique blocked browsers (distinct browsers that have hit the ban), so you can see which bans are doing work example get to kindly curl request get \\ \ url https //bot kindly ai/api/v2/chat bans \\ \ header 'authorization bearer your api key' response { "bans" \[ { "id" "\<ban id>", "ip address" "\<ip address>", "reason" "spam", "banned by agent id" "\<agent id>", "banned at" "2026 05 14t08 30 00 000z", "expires at" "2026 06 01t00 00 00 000z", "chat id" "\<chat id>", "blocked count" 17, "unique blocked browsers" 3 } ] }