Skip to content

docs(ENG-57601): add Bots section to the REST API reference - #626

Merged
ketanyekale merged 3 commits into
mainfrom
docs/restapi-chat-api-ENG-57601
Nov 19, 2026
Merged

ketanyekale merged 3 commits into
mainfrom
docs/restapi-chat-api-ENG-57601

Conversation

@pranavkamble-cometchat

Copy link
Copy Markdown
Contributor

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 only POST /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, a Bots navigation group, and the five operations in chat-apis.json.

chat-apis.json was not hand-edited. The five operations and the Bots tag 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.json and data-import-apis.json are untouched. The diff is 645 insertions and 0 deletions.

Companion PR in chat-api adds the OAS annotations this spec was generated from: https://github.com/cometchat-team/chat-api/pull/2618

Related Issue(s)

ENG-57601

Type of Change

  • New documentation

Checklist

  • I have read the CONTRIBUTING document
  • My branch name follows the naming convention
  • My changes follow the documentation style guide
  • I have checked for spelling and grammar errors
  • All links in my changes are valid and working
  • My changes are accurately described in this pull request

Additional Information

Pages

Page Operation
rest-api/bots.mdx Overview — endpoints table, how bots work, relationships, properties, errors
rest-api/bots/list.mdx GET /bots
rest-api/bots/create.mdx POST /bots
rest-api/bots/get.mdx GET /bots/{uid}
rest-api/bots/update.mdx PUT /bots/{uid}
rest-api/bots/delete.mdx DELETE /bots/{uid}

Navigation: a Bots group under REST API → Users & Groups, immediately after Users. No page is moved or renamed, so no redirects are needed.

Deliberate omissions

  • avatar is not documented on POST /bots. It passes validation and is then discarded on a public call — it is in neither Bot::$fillable nor APIInterface::$fillable. A bot's avatar belongs to its user, so the create page points at the Update User API instead.
  • isAIBot is 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 default GET /bots; documenting it on create would publish a supported way to create an invisible bot. AI bots are created through AI Agents.
  • useCursoredIndex and unset are sent by some callers but read by no bot code path, so they stay undocumented.

Behaviour the pages call out

  • enabled defaults to false, 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.
  • groupChatSetting defaults to none.
  • Responses drop every falsy value, so false booleans and empty strings never appear.
  • When useBasicAuth is true the API returns the stored password in 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

Command Result
mint broken-links success no broken links found
mint dev All six pages render 200; request bodies, query parameters, response examples and the playground render; every link on the overview resolves
Tag-scoped merge re-run against a pristine main copy Reproduces this branch's chat-apis.json exactly; 172 pre-existing operations and all components byte-identical

mint broken-links emits one warning, Error validating OpenAPI file /docs.json. It is pre-existing — the same command on main at 8a3486b0 emits it identically.

mint requires 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.

Co-authored-by: multica-agent <github@multica.ai>
…claims

Co-authored-by: multica-agent <github@multica.ai>
@mintlify

mintlify Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated
cometchat 🟢 Ready View Preview Nov 19, 2026, 3:27 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

@siva-cometchat siva-cometchat left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

  1. Update and basic auth. username/password are discarded only on Create, when useBasicAuth is 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 drops useBasicAuth (falsy) but still returns username and password.
    • PUT {"username": "...", "password": "..."} on a bot without basic auth stores both and returns them.
    • So the "Stored only when / Ignored unless useBasicAuth is true" wording is wrong for Update. The password-exposure warnings should also cover bots that had basic auth and then turned it off.
  2. "AI bots are created through AI Agents" looks wrong. Bots created by AI Agents (the internal-domain path) get type = 'agentic' and never set isAIBot. App\Models\V3\Bot adds the global scope ExcludeProtectedScope('type', 'agentic'), so agents are hidden from every public bot endpoint:
    • They never appear in GET /bots?isAIBot=true.
    • checkBot returns ERR_BOT_NOT_FOUND for their UIDs on Get, Update and Delete.
    • isAIBot=true only returns rows where the isAIBot column 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-agent examples. It would also help to say that AI Agent UIDs aren't reachable through these endpoints.

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.

Comment thread rest-api/bots.mdx Resolved
Comment thread rest-api/bots.mdx Resolved
Comment thread rest-api/bots.mdx Resolved
Comment thread rest-api/bots/update.mdx Resolved
Comment thread rest-api/bots/list.mdx Resolved
Comment thread rest-api/bots/list.mdx Resolved
Comment thread rest-api/bots/get.mdx Resolved
Comment thread chat-apis.json Resolved
Comment thread chat-apis.json Resolved
Comment thread rest-api/bots/create.mdx Resolved

@ketanyekale ketanyekale left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Concur with @siva-cometchat's review. I checked items 1 and 2 against the chat-api source on ENG-57601, and both hold:

  • update() stores username/password as sent and never clears them when useBasicAuth goes false (BotController.php:385; the unset exists only in create()). 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 the Bot model's global scope. They don't appear under isAIBot=true, and their UIDs return ERR_BOT_NOT_FOUND on 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>
@siva-cometchat

Copy link
Copy Markdown
Contributor

The review fixes are in place in b32f071:

  • Update and basic auth: the overview property rows, the response note, the Update page and the password warnings now say that Update stores username/password as sent, and that setting useBasicAuth to false doesn't clear them. The credentials still appear in responses.
  • AI Agents: the pages no longer say AI bots come from AI Agents. They now say agents aren't returned by List and return ERR_BOT_NOT_FOUND on Get, Update and Delete. The research-agent examples are now faq-bot.
  • update-bot schema: the Bots operations in chat-apis.json were re-merged from the regenerated chat-api OAS (cometchat-team/chat-api#2618, 2b8dc8991). The Update request body no longer has defaults, and the isAIBot and basic-auth descriptions are corrected. Only those lines changed.
  • 25 bots per app: I removed the "Bots per app" row from Create, because this API doesn't enforce it.

mint broken-links: no broken links.

isAIBot is a label only. It's set on create, filtered by List and returned in responses, with no other behaviour. It most likely marks the legacy dashboard "AI Bots", so the pages use the neutral wording "flagged as an AI bot".

@siva-cometchat siva-cometchat left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 ketanyekale left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@ketanyekale
ketanyekale merged commit ec1e3df into main Nov 19, 2026
5 checks passed

This branch was successfully deployed

1 active deployment
staging — b32f071d Deployed Nov 19, 2026 by mintlify[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

3 participants