Repository navigation
docs(ENG-57601): add Bots section to the REST API reference - #626
Conversation
Co-authored-by: multica-agent <github@multica.ai>
…claims Co-authored-by: multica-agent <github@multica.ai>
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Automations to automatically generate PRs for you. |
siva-cometchat
left a comment
There was a problem hiding this comment.
Thanks for this. The structure, navigation and additive spec merge look good. I checked every behaviour claim against the chat-api source, and most of them hold up. Two things need fixing before merge, plus one spec tweak and a nit. Details are in the inline comments.
Must fix
- Update and basic auth.
username/passwordare discarded only on Create, whenuseBasicAuthis falsy (app/Http/Controllers/V3/Admin/V3_0/BotController.php,create():unset($botData['username'])).update()passes the validated body straight to$bot->update($botData). As a result:PUT {"useBasicAuth": false}keeps the stored credentials. The response then dropsuseBasicAuth(falsy) but still returnsusernameandpassword.PUT {"username": "...", "password": "..."}on a bot without basic auth stores both and returns them.- So the "Stored only when / Ignored unless
useBasicAuthistrue" wording is wrong for Update. The password-exposure warnings should also cover bots that had basic auth and then turned it off.
- "AI bots are created through AI Agents" looks wrong. Bots created by AI Agents (the internal-domain path) get
type = 'agentic'and never setisAIBot.App\Models\V3\Botadds the global scopeExcludeProtectedScope('type', 'agentic'), so agents are hidden from every public bot endpoint:- They never appear in
GET /bots?isAIBot=true. checkBotreturnsERR_BOT_NOT_FOUNDfor their UIDs on Get, Update and Delete.isAIBot=trueonly returns rows where theisAIBotcolumn was set, which looks like a legacy flag.- Please confirm with the API team what actually creates these bots, then update the wording and the
research-agentexamples. It would also help to say that AI Agent UIDs aren't reachable through these endpoints.
- They never appear in
Should fix
3. PUT update-bot schema defaults. enabled and useBasicAuth have default: false, and the string fields have default: "". For a partial update, that reads as "leaving it out sets it to false/empty". The existing Users PUT has no defaults. This file is generated, so the fix probably belongs in the companion chat-api PR.
Nit
4. 25 bots per app. The "Bots per app: 25" row isn't enforced by this API: neither create() nor checkBotAccess counts bots. Either it's enforced elsewhere (dashboard or billing), or the row should be softened.
Verified correct: enabled/groupChatSetting defaults, perPage default and cap (middleware maps perPage to per_page), searchKey prefix match and UID ordering, UID lowercasing, falsy-value filtering, updatedAt omission, Delete keeping the user, the delete success message, the error codes, and that all internal links resolve.
ketanyekale
left a comment
There was a problem hiding this comment.
Concur with @siva-cometchat's review. I checked items 1 and 2 against the chat-api source on ENG-57601, and both hold:
update()storesusername/passwordas sent and never clears them whenuseBasicAuthgoes false (BotController.php:385; theunsetexists only increate()). The Update page and the overview's property and password wording need to reflect this.- AI Agent bots are
type = 'agentic'and are hidden by theBotmodel's global scope. They don't appear underisAIBot=true, and their UIDs returnERR_BOT_NOT_FOUNDon Get/Update/Delete.
Items 1 and 3 originate in the chat-api annotations. I've requested changes on cometchat-team/chat-api#2618, so please fix them there, regenerate, and re-merge the five operations into chat-apis.json.
- Update stores username/password as sent and never clears them when useBasicAuth is set to false; reword the overview property rows, the response note, the Update page and the password warnings to match. - Bots created through AI Agents (type agentic) are hidden from every public bot endpoint; stop describing isAIBot bots as AI Agents, swap the research-agent examples for faq-bot, and note ERR_BOT_NOT_FOUND for agents. - Re-merge the Bots operations from the regenerated chat-api OAS: drop the defaults from the update-bot request body and reword the isAIBot and basic auth descriptions. - Drop the "Bots per app" row from Create; this API does not enforce it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
The review fixes are in place in b32f071:
|
siva-cometchat
left a comment
There was a problem hiding this comment.
Fixes verified: Update basic-auth behaviour, the AI Agents wording, the re-merged update-bot schema and the Create constraints row now match chat-api. Approving.
ketanyekale
left a comment
There was a problem hiding this comment.
Re-reviewed b32f071. The update/basic-auth behaviour is now described correctly on the overview, Update, Get and List pages, including the password warnings. AI Agents are called out as unreachable through these endpoints. The research-agent examples are now faq-bot, and the unenforced 25-bot row is gone. The /bots and /bots/{uid} paths in chat-apis.json are byte-identical to cometchat-team/chat-api#2618 at 2b8dc8991, and the spec has 177 operations. LGTM.
Description
Documents the five admin Bot endpoints (
POST /bots,GET /bots,GET /bots/{uid},PUT /bots/{uid},DELETE /bots/{uid}) as a new Bots section of the public REST API reference. Until now onlyPOST /bots/{uid}/messages(Send Bot Message) was documented, so customers who wanted to manage bots over the API had no documented path and were pointed at the dashboard.Adds six pages under
/docs/rest-api/bots, aBotsnavigation group, and the five operations inchat-apis.json.chat-apis.jsonwas not hand-edited. The five operations and theBotstag were merged in from the regenerated chat-api OAS with a tag-scoped merge that refuses to touch anything else. Result: 172 → 177 operations, 17 → 18 tags, all 172 pre-existing operations and every pre-existing component byte-identical, zero components added.calls.jsonanddata-import-apis.jsonare untouched. The diff is 645 insertions and 0 deletions.Companion PR in
chat-apiadds the OAS annotations this spec was generated from: https://github.com/cometchat-team/chat-api/pull/2618Related Issue(s)
ENG-57601
Type of Change
Checklist
Additional Information
Pages
rest-api/bots.mdxrest-api/bots/list.mdxGET /botsrest-api/bots/create.mdxPOST /botsrest-api/bots/get.mdxGET /bots/{uid}rest-api/bots/update.mdxPUT /bots/{uid}rest-api/bots/delete.mdxDELETE /bots/{uid}Navigation: a
Botsgroup under REST API → Users & Groups, immediately afterUsers. No page is moved or renamed, so no redirects are needed.Deliberate omissions
avataris not documented onPOST /bots. It passes validation and is then discarded on a public call — it is in neitherBot::$fillablenorAPIInterface::$fillable. A bot's avatar belongs to its user, so the create page points at the Update User API instead.isAIBotis documented as a list filter and a response field, not as a create field. It persists if sent, and the bot then disappears from the defaultGET /bots; documenting it on create would publish a supported way to create an invisible bot. AI bots are created through AI Agents.useCursoredIndexandunsetare sent by some callers but read by no bot code path, so they stay undocumented.Behaviour the pages call out
enableddefaults tofalse, so a create that omits it produces a bot that relays nothing. Called out on the create page and in the overview's property table.groupChatSettingdefaults tonone.falsebooleans and empty strings never appear.useBasicAuthistruethe API returns the storedpasswordin responses to Create, List, Get and Update. Every example masks it as********and the pages say in words that a real response contains the value. A follow-up ticket for the API behaviour is being raised separately; it does not block these pages.Checks
mint broken-linkssuccess no broken links foundmint devmaincopychat-apis.jsonexactly; 172 pre-existing operations and all components byte-identicalmint broken-linksemits one warning,Error validating OpenAPI file /docs.json. It is pre-existing — the same command onmainat8a3486b0emits it identically.mintrequires an LTS Node; it refuses Node 25+.Risk and rollback
Low. Six new pages, one navigation group, and an additive-only spec change — no existing page, operation or component is modified. Rollback is reverting the single commit.
Release notes
New: Bots REST API reference — create, list, get, update and delete bots over the API.
QA notes
The Mintlify playground issues live calls, so an end-to-end check needs an app with bots enabled and an API key. The five endpoints were exercised against a non-production app on 2026-11-19: create, list, get, update and delete all returned 200, and a get after delete returned 404
ERR_BOT_NOT_FOUND.Agent-built with Claude Code, reviewed by Pranav Kamble.