(EAI-1274): Rate and comment endpoints based only on message id

docs/docs/server/openapi.yaml

@@ -246,10 +246,15 @@ paths:
   #         $ref: "#/components/responses/InternalServerError"
   /conversations/{conversationId}/messages/{messageId}/rating:
     post:
+      deprecated: true
       operationId: rateMessage
       tags:
         - Conversations
       summary: Rate message
+      description: |
+        Rate a message.
+
+        This endpoint is deprecated. Use the [rateStandaloneMessage](#operation/rateStandaloneMessage) endpoint instead.
       parameters:
         - $ref: "#/components/parameters/conversationId"
         - $ref: "#/components/parameters/messageId"
@@ -267,9 +272,32 @@ paths:
           $ref: "#/components/responses/NotFound"
         500:
           $ref: "#/components/responses/InternalServerError"
+  /conversations/messages/{messageId}/rating:
+    post:
+      operationId: rateStandaloneMessage
+      tags:
+        - Conversations
+      summary: Rate message
+      parameters:
+        - $ref: "#/components/parameters/messageId"
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/MessageRating"
+      responses:
+        204:
+          description: Rating Saved
+        400:
+          $ref: "#/components/responses/BadRequest"
+        404:
+          $ref: "#/components/responses/NotFound"
+        500:
+          $ref: "#/components/responses/InternalServerError"
 
   /conversations/{conversationId}/messages/{messageId}/comment:
     post:
+      deprecated: true
       operationId: commentMessage
       tags:
         - Conversations
@@ -295,6 +323,32 @@ paths:
           $ref: "#/components/responses/NotFound"
         500:
           $ref: "#/components/responses/InternalServerError"
+  /conversations/messages/{messageId}/comment:
+    post:
+      operationId: commentStandaloneMessage
+      tags:
+        - Conversations
+      summary: Add comment to assistant message
+      description: |
+        Add a comment to an assistant message that clarifies a thumbs up/down rating.
+
+        You can only rate an an assistant message that has a thumbs up/down rating. You can only rate a message once. The server returns a `400` error response if the message is not from the assistant, is not rated, or has already been rated.
+      parameters:
+        - $ref: "#/components/parameters/messageId"
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/MessageComment"
+      responses:
+        204:
+          description: Comment Saved
+        400:
+          $ref: "#/components/responses/BadRequest"
+        404:
+          $ref: "#/components/responses/NotFound"
+        500:
+          $ref: "#/components/responses/InternalServerError"
   /responses:
     post:
       operationId: createResponse

docs/docs/server/responses-api.md

@@ -494,8 +494,8 @@ const stream = await openai.responses.create({
 
 You can collect user feedback in the form of message ratings and comments on all generations from the Responses API. The Knowledge Service has separate endpoints for rating and commenting messages:
 
-- [`rateMessage` endpoint](/server/openapi/#tag/Conversations/operation/rateMessage)
-- [`commentMessage` endpoint](/server/openapi/#tag/Conversations/operation/commentMessage)
+- [`rateStandaloneMessage` endpoint](/server/openapi/#tag/Conversations/operation/rateStandaloneMessage)
+- [`commentStandaloneMessage` endpoint](/server/openapi/#tag/Conversations/operation/commentStandaloneMessage)
 
 Usage example:
 
@@ -518,21 +518,19 @@ const stream = await openai.responses.create({
 });
 
 let messageId: string;
-let conversationId: string;
 
 for await (const event of stream) {
   switch(event.type) {
     case "response.completed":
       // Extract the message ID and conversation ID for rating/commenting
       messageId = event.response.id;
-      conversationId = event.response.metadata.conversation_id;
       break;
     // ...other event handling
   }
 }
 
 // Rate the message (thumbs up/down)
-const rateResponse = await fetch(`${knowledgeServiceBaseUrl}/conversations/${conversationId}/messages/${messageId}/rating`, {
+const rateResponse = await fetch(`${knowledgeServiceBaseUrl}/conversations/messages/${messageId}/rating`, {
   method: 'POST',
   headers: {
     'Content-Type': 'application/json',
@@ -544,7 +542,7 @@ const rateResponse = await fetch(`${knowledgeServiceBaseUrl}/conversations/${con
 });
 
 // Add a comment to the message (requires the message to be rated first)
-const commentResponse = await fetch(`${knowledgeServiceBaseUrl}/conversations/${conversationId}/messages/${messageId}/comment`, {
+const commentResponse = await fetch(`${knowledgeServiceBaseUrl}/conversations/messages/${messageId}/comment`, {
   method: 'POST',
   headers: {
     'Content-Type': 'application/json',