docs(rest-api): add pin, save & interacted endpoints (ENG-38785)

[pranavkamble-cometchat]

Re-sync chat-apis.json and data-import-apis.json from the chat-api OAS, and add the 11 endpoint pages plus navigation entries for the new message and conversation operations.

Description

Related Issue(s)

Type of Change

• Documentation correction/update
• New documentation
• Improvement to existing documentation
• Typo fix
• Other (please specify)

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

Screenshots (if applicable)

[mintlify]

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

Project	Status	Preview	Updated (UTC)
cometchat	🟢 Ready	View Preview	Sep 2, 2026, 11:04 AM

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

[pranavkamble-cometchat]

Review points — all addressed

Every finding is fixed at source in cometchat-team/chat-api (branch ENG-38785) rather than
patched here, so the specs stay correct on the next re-sync. This PR carries the regenerated output.

P0

1. category removed from the Send Message body
Restored on messageCategorySchema and customCategorySchema, in both chat-apis.json and
data-import-apis.json. Confirmed required by the API (MessageController.php:947;
MessageCore.php:5260 raises ERR_EMPTY_MESSAGE_CATEGORY). The three request examples that still
sent it, and the attachments / customData descriptions that reference it, are consistent again.

2. Broken discriminator on POST /bots/{uid}/messages
Fixed by #1 — all three schemas in the mapping now carry category, so the discriminator resolves.

3. mentionsWithTagInfo → mentionswithTagInfo
Reverted to the capital-W form on all three operations (GET /messages,
GET /users/{uid}/messages, GET /groups/{guid}/messages). Fixed in the OAS source, so it won't
come back.

P1

4. calls.json moving backwards
Dropped from this PR entirely — it regenerates byte-identical to main, so it carried no legitimate
change. Both regressions ({appid}, retreive-call-details) are fixed upstream.

5. Error guide documents none of the new codes
All five added to articles/error-guide.mdx: ERR_PINNED_MESSAGES_LIMIT_EXCEEDED,
ERR_SAVED_MESSAGES_LIMIT_EXCEEDED, ERR_PINNED_CONVERSATIONS_LIMIT_EXCEEDED,
ERR_SYSTEM_PINNED_CONVERSATIONS_LIMIT_EXCEEDED, ERR_SYSTEM_PINNED_CONVERSATION.

6. 8 of 11 endpoints render an empty or nameless data object
Both broken annotation forms replaced with @OA\Property(property="data", ref="…") on all nine
affected operations. The four conversation-pin endpoints now render the pinnedBy / pinnedAt
fields this PR adds to conversationSchema. The array form on GET/PUT /conversations/pinned was
already correct and is untouched.

7. Three names for one concept
operationId, page slug and nav entry now all say global
(list-global-pinned-conversations, replace-global-pinned-conversations). The two OAS source
files were renamed to match, so filename == operationId holds as it does elsewhere in the section.

P2 / nits

• Two prose regressions — unique parameter description and
  Mark Group Conversation As Unread both restored.
• Summary casing — all 11 new summaries re-cased to Title Case, matching sibling operations.
• interactive dropped from the Send Message oneOf — restored, along with the discriminator.
• Five /moderation/messages* operations with no page or nav entry — kept in the spec
  deliberately. They're real on dev; the docs were behind. Pages are a separate decision.
• onBehalfOf inline on pin-message/unpin-message — kept inline on purpose. The shared
  component reads "UID of the user on whose behalf the action is performed"; the inline text says
  "Leave it out to pin the message as the app itself", which is this endpoint's actual semantics.
• sort_order.php vs nav ordering — left as-is. Cosmetic, and nav wins.

Additional fixes found while tracing the same root cause

The re-sync had reverted more docs-only fixes than the review caught. All restored:

• Two operations had undeclared path parameters — role on GET /roles/{role}/permissions, and
  guid + scope on GET /groups/{guid}/scopes/{scope}/permissions. A path template variable with
  no declared parameter is invalid OpenAPI and leaves no input field in the playground.
• Pagination lost on GET /roles, GET /users/{uid}/blockedusers, GET /users/{uid}/auth_tokens
  and GET /groups/{guid}/bannedusers (page, perPage).
• Four cursor parameters lost on GET /messages/{id}/thread (affix, id query, sentAt,
  limit).
• operationId dropped on all three /users/{uid}/blockedusers operations.
• A third summary regression of the same kind as the nit above —
  Mark Conversation Messages As Unread.

Also improved on PATCH /messages/{id}/interacted: description expanded to cover the
interactive-category constraint and idempotency, requestBody marked required,
required: ["interactions"] added.

One deviation from the agreed fix list

PATCH /messages/{id}/interacted resolves to deleteSchema, not messageSchema. The endpoint
returns {success, message} (MessageCore::markAsInteracted), matching its own 200 example — the
original annotation had both the wrong pattern and the wrong target schema.

Verification

Checked mechanically against main @ 20e18728:

Check	Result	Covers
Pre-existing operations changed / removed	0 / 0	the regression class behind #1, #3, #4 and the prose nits
Operations added	16	11 pin/save/interacted + 5 moderation
Unresolved discriminators	0	#2
New malformed response payloads	0	#6
operationIds dropped	0	blocked-users restore
Undeclared path parameters	0	role, guid+scope restore

Nav refs, orphans, in-content links and redirect coverage are unchanged since your review —
docs.json and every rest-api/*.mdx page are untouched by this commit.