CometChat REST API Documentation Audit Report
Date: 2026-04-24 Branch:docs/restapi-chatapi-ENG-30061-ketan
Preview URL: https://cometchat-22654f5b-docs-restapi-chatapi-eng-30061-ketan.mintlify.app/
Pages Scanned: 3,090 MDX files across 10 product directories
OAS Files Scanned: 5 files with 345 total endpoints
Executive Summary
| Dimension | Score |
|---|---|
| Enterprise Readiness | 7.5/10 |
| AI-Agent Friendliness | 7.0/10 |
| AEO Friendliness | 8.5/10 |
| Link Hygiene | 8.0/10 |
| Completeness | 7.5/10 |
| Consistency | 7.0/10 |
| Overall (weighted) | 7.5/10 |
data: object responses in chat-apis.json), 4 broken redirect destinations, and cross-product consistency in overview page structure.
Product Coverage
| Product | OAS File | Endpoints | MDX Pages | Guide Pages | Status |
|---|---|---|---|---|---|
| Chat & Messaging | chat-apis.json | 130 | 404 | 26 (notifications) | Active |
| Voice & Video Calling | calls.json | 2 | 207 | — | Active |
| AI Agents | ai-agent-service.json | 68 | 86 | — | Active |
| Moderation | management-apis.json | 141 | 12 | — | Active |
| Data Import | data-import-apis.json | 4 | — | — | Active |
Score Breakdown
Enterprise Readiness: 7.5/10
All 345 endpoints have operationIds and zero empty example values. Authentication is documented per-product (apikey for Chat, Basic Auth for Management). The main gap is 52 endpoints in chat-apis.json returningdata as a generic untyped object — enterprise SDK codegen and type-safe clients can’t infer response structure. 14 endpoints have completely empty response schemas.
AI-Agent Friendliness: 7.0/10
100% operationId coverage is excellent for AI agent consumption. Thellms.txt file is published and accessible. However, 35 list endpoints across 3 OAS files lack pagination metadata in response schemas, making it harder for agents to handle paginated results programmatically. The 52 untyped response objects in chat-apis.json are the biggest blocker for AI agent integration.
AEO Friendliness: 8.5/10
Every REST API MDX file has a frontmatterdescription. The llms.txt is published with clear page descriptions. Heading hierarchy is clean across all scanned pages. Overview pages have structured endpoint tables (except AI Agents overview which uses prose instead). No debug markers in REST API pages.
Link Hygiene: 8.0/10
Zero broken internal links in REST API pages. Zero legacy domain references. Zero orphan or ghost pages. However, 4 redirect destinations point to non-existent files (/ai-chatbots/ai-bots/bots, /ai-chatbots/ai-bots/instructions, /widget/wordpress/legacy, /widget/html/legacy). The flutter-sdk-changes-review.md file (286 <br> tags fixed in this branch) and 13 files with invalid mintlify imports were cleaned up.
Completeness: 7.5/10
REST API overview pages for Calls and Moderation are comprehensive with endpoint tables, property tables, error handling, and pagination examples. AI Agents overview is lighter — missing a structured endpoint table. The iOS APNs push notification page renders as code-only with no prose introduction. 11 TODO markers remain in iOS UI Kit and React Native notification pages (screenshots and code snippets needed).Consistency: 7.0/10
Overview page structure varies across products — Calls and Moderation have full endpoint tables while AI Agents uses prose. Pagination parameter naming varies across OAS files (perPage/count/limit) — this is an API-contract issue, not a docs issue. Code fence formatting was inconsistent (3 vs 4 backtick closings) across 10 JavaScript SDK files — fixed in this branch. Duplicate frontmatter keys were found in 2 files — fixed in this branch.
Issues Found
CRITICAL (P0)
| # | Issue | File/Product | Dimension | Suggested Fix |
|---|---|---|---|---|
| 1 | 52 endpoints return data as untyped generic object | chat-apis.json | Enterprise Readiness, AI-Agent | Add typed response schemas with properties for each endpoint |
HIGH (P1)
| # | Issue | File/Product | Dimension | Suggested Fix |
|---|---|---|---|---|
| 2 | 35 list endpoints missing pagination metadata in response schema | chat-apis.json, management-apis.json, ai-agent-service.json | AI-Agent Friendliness | Add meta/pagination object to list endpoint response schemas |
| 3 | 23 endpoints with empty response schemas | chat-apis.json (14), calls.json (2), ai-agent-service.json (7) | Enterprise Readiness | Define response properties or document as 204 No Content |
| 4 | 4 broken redirect destinations | docs.json redirects | Link Hygiene | Remove or update redirects for /ai-chatbots/ai-bots/bots, /ai-chatbots/ai-bots/instructions, /widget/wordpress/legacy, /widget/html/legacy |
MEDIUM (P2)
| # | Issue | File/Product | Dimension | Suggested Fix |
|---|---|---|---|---|
| 5 | AI Agents API overview lacks structured endpoint table | rest-api/ai-agents-apis/overview | Completeness, Consistency | Add endpoint table matching Calls/Moderation overview format |
| 6 | iOS APNs push notification page is code-only | notifications/ios-apns-push-notifications.mdx | Completeness | Add introductory prose, setup steps, and section headers |
| 7 | 11 TODO markers in iOS UI Kit and RN notification pages | ui-kit/ios/.mdx, notifications/react-native-.mdx | Completeness | Add missing screenshots and code snippets |
LOW (P3)
| # | Issue | File/Product | Dimension | Suggested Fix |
|---|---|---|---|---|
| 8 | AWSCLIV2.pkg in repo root (skipped by Mintlify as too large) | Root | Link Hygiene | Add to .gitignore or remove from repo |
| 9 | Calls OAS has only 2 endpoints with empty 400 error schemas | calls.json | Enterprise Readiness | Add error response properties |
Fixes Applied in This Branch
The following issues were discovered and fixed during this audit session:| Fix | Files | Change |
|---|---|---|
| Duplicate redirect source | docs.json | Removed duplicate /notifications/push-notification-extension-overview, kept assets.cometchat.io destination |
<br> → <br/> | flutter-sdk-changes-review.md | 286 self-closing HTML tags for MDX compatibility |
| Mismatched code fences | 10 MDX files (ios-apns, ios-fcm, 8 JS SDK files) | Fixed ``````` closings to match `` openings |
| Inline code fences | sdk/javascript/retrieve-users.mdx, send-message.mdx | Expanded single-line code fences to proper multi-line blocks |
| Escaped comment syntax | sdk/javascript/send-message.mdx | Fixed {/\* → {/* and \*/} → */} |
| Duplicate frontmatter keys | sdk/android/changelog.mdx, sdk/flutter/ai-chatbots-overview.mdx | Removed duplicate description keys |
| Invalid mintlify imports | 13 MDX files across calls, widget, ai-agents | Removed import { ... } from 'mintlify' (components are globally available) |
Prioritized Fix List
P0 — Must fix (blocks SDK codegen / AI agent consumption)
- Add typed response schemas to 52 chat-apis.json endpoints returning generic
data: object
P1 — Should fix (degrades developer experience)
- Add pagination metadata to 35 list endpoint response schemas
- Define response properties for 23 empty response schemas
- Fix or remove 4 broken redirect destinations in docs.json
P2 — Nice to fix (polish)
- Add structured endpoint table to AI Agents API overview page
- Add prose introduction to iOS APNs push notification page
- Resolve 11 TODO markers (screenshots, code snippets)
P3 — Backlog
- Remove
AWSCLIV2.pkgfrom repo - Add error response schemas to calls.json
Appendix
- Total issues: 9
- By severity: 1 critical, 3 high, 3 medium, 2 low
- By product: Chat 3, Calls 1, AI Agents 1, Cross-product 4
- Pages with zero issues: 3,070+ of 3,090
- OAS files scanned: chat-apis.json (130), calls.json (2), data-import-apis.json (4), management-apis.json (141), ai-agent-service.json (68)
- Branch fixes applied: 3 commits fixing 27 files total