docs: update api reference messages

docs/docs/specs/messages.md

@@ -255,4 +255,162 @@ See [Jan Messages API](https://jan.ai/api-reference#tag/Messages)
   "created_at": 1699061776,
   "message_id": "msg_abc123"
 }
-``` -->
+``` -->
+### Get list message
+
+> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/messages/getMessage
+
+- Example request
+
+```shell
+  curl {JAN_URL}/v1/threads/{thread_id}/messages/{message_id} \
+    -H "Content-Type: application/json"
+```
+
+- Example response
+
+```json
+{
+  "id": "msg_abc123",
+  "object": "thread.message",
+  "created_at": 1699017614,
+  "thread_id": "thread_abc123",
+  "role": "user",
+  "content": [
+    {
+      "type": "text",
+      "text": {
+        "value": "How does AI work? Explain it in simple terms.",
+        "annotations": []
+      }
+    }
+  ],
+  "file_ids": [],
+  "assistant_id": null,
+  "run_id": null,
+  "metadata": {}
+}
+```
+
+### Create message
+
+> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/messages/createMessage
+
+- Example request
+
+```shell
+  curl -X POST {JAN_URL}/v1/threads/{thread_id}/messages \
+    -H "Content-Type: application/json" \
+    -d '{
+      "role": "user",
+      "content": "How does AI work? Explain it in simple terms."
+    }'
+```
+
+- Example response
+
+```json
+{
+  "id": "msg_abc123",
+  "object": "thread.message",
+  "created_at": 1699017614,
+  "thread_id": "thread_abc123",
+  "role": "user",
+  "content": [
+    {
+      "type": "text",
+      "text": {
+        "value": "How does AI work? Explain it in simple terms.",
+        "annotations": []
+      }
+    }
+  ],
+  "file_ids": [],
+  "assistant_id": null,
+  "run_id": null,
+  "metadata": {}
+}
+```
+
+### Get message
+
+> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/assistants/listAssistants
+
+- Example request
+
+```shell
+  curl {JAN_URL}/v1/threads/{thread_id}/messages/{message_id} \
+    -H "Content-Type: application/json"
+```
+
+- Example response
+
+```json
+{
+  "id": "msg_abc123",
+  "object": "thread.message",
+  "created_at": 1699017614,
+  "thread_id": "thread_abc123",
+  "role": "user",
+  "content": [
+    {
+      "type": "text",
+      "text": {
+        "value": "How does AI work? Explain it in simple terms.",
+        "annotations": []
+      }
+    }
+  ],
+  "file_ids": [],
+  "assistant_id": null,
+  "run_id": null,
+  "metadata": {}
+}
+```
+
+### Modify message
+
+> Jan: TODO: Do we need to modify message? Or let user create new message?
+
+# Get message file
+
+> OpenAI Equivalent: https://api.openai.com/v1/threads/{thread_id}/messages/{message_id}/files/{file_id}
+
+- Example request
+
+```shell
+  curl {JAN_URL}/v1/threads/{thread_id}/messages/{message_id}/files/{file_id} \
+    -H "Content-Type: application/json"
+```
+
+- Example response
+
+```json
+{
+  "id": "file-abc123",
+  "object": "thread.message.file",
+  "created_at": 1699061776,
+  "message_id": "msg_abc123"
+}
+```
+
+# List message files
+
+> OpenAI Equivalent: https://api.openai.com/v1/threads/{thread_id}/messages/{message_id}/files
+
+````
+- Example request
+```shell
+  curl {JAN_URL}/v1/threads/{thread_id}/messages/{message_id}/files/{file_id} \
+    -H "Content-Type: application/json"
+````
+
+- Example response
+
+```json
+{
+  "id": "file-abc123",
+  "object": "thread.message.file",
+  "created_at": 1699061776,
+  "message_id": "msg_abc123"
+}

docs/openapi/jan.yaml

@@ -17,10 +17,18 @@ tags:
   - name: Chat Completion
     description: Given a list of messages comprising a conversation, the model will return a response.
   - name: Messages
-    description: Operations for individual messages, including creation, retrieval, and modification
+    description: |
+      Messages capture a conversation's content. This can include the content from LLM responses and other metadata from [chat completions](/specs/chats).
+
+      - Users and assistants can send multimedia messages.
+
+      - An [OpenAI Message API](https://platform.openai.com/docs/api-reference/messages) compatible endpoint at `localhost:1337/v1/messages`.
+
+      - Jan's `messages` API is compatible with [OpenAI's Messages API](https://platform.openai.com/docs/api-reference/messages), with additional methods for managing messages locally.
+
   - name: Threads
     description: |
-      `Threads` are conversations between an `assistant` and the user:
+      Threads are conversations between an `assistant` and the user:
         - Users can tweak `model` params and `assistant` behavior within each thread.
         - Users can import and export threads.
         - An [OpenAI Thread API](https://platform.openai.com/docs/api-reference/threads) compatible endpoint at `localhost:1337/v1/threads`. 
@@ -428,8 +436,8 @@ paths:
       operationId: listMessages
       tags:
         - Messages
-      summary: Get a list of messages from a thread
+      summary: List messaages
-      description: Retrieves all messages from the specified thread.
+      description: Retrieves all messages from the given thread.
       parameters:
         - in: path
           name: thread_id
@@ -454,8 +462,8 @@ paths:
       operationId: createMessage
       tags:
         - Messages
-      summary: Create a new message in a thread
+      summary: Create message
-      description: Sends a new message to the specified thread.
+      description: Create a message
       parameters:
         - in: path
           name: thread_id
@@ -493,13 +501,16 @@ paths:
       x-codeSamples:
         - lang: "curl"
           source: |
-            curl -X POST {JAN_URL}/v1/threads/{thread_id}/messages \
+              curl -X POST {JAN_URL}/v1/threads/{thread_id}/messages \
-              -H "Content-Type: application/json" \
+                -H "Content-Type: application/json" \
-              -d '{"role": "user", "content": "How does AI work? Explain it in simple terms."}'
+                -d '{
+                  "role": "user",
+                  "content": "How does AI work? Explain it in simple terms."
+                }'
 
   /threads/{thread_id}/messages/{message_id}:
     get:
-      operationId: getMessage
+      operationId: retrieveMessage
       tags:
         - Messages
       summary: Retrieve Message
@@ -529,16 +540,16 @@ paths:
       x-codeSamples:
         - lang: "curl"
           source: |
-            curl {JAN_URL}/v1/threads/{thread_id}/messages/{message_id} \
+                curl {JAN_URL}/v1/threads/{thread_id}/messages/{message_id} \
-              -H "Content-Type: application/json"
+                  -H "Content-Type: application/json"
 
   /threads/{thread_id}/messages/{message_id}/files:
     get:
       operationId: listMessageFiles
       tags:
         - Messages
-      summary: message files
+      summary: List message files
-      description: Retrieves a list of files associated with a specific message in a thread.
+      description: Returns a list of message files.
       parameters:
         - in: path
           name: thread_id
@@ -569,10 +580,10 @@ paths:
 
   /threads/{thread_id}/messages/{message_id}/files/{file_id}:
     get:
-      operationId: getMessageFile
+      operationId: retrieveMessageFile
       tags:
         - Messages
-      summary: Get message file
+      summary: Retrieve message file
       description: Retrieves a file associated with a specific message in a thread.
       parameters:
         - in: path

docs/openapi/specs/messages.yaml

@@ -6,11 +6,11 @@ components:
         id:
           type: string
           description: "Sequential or UUID identifier of the message."
-          example: "0"
+          example: 0
         object:
           type: string
-          description: "Type of the object, typically 'thread.message'."
+          description: "Type of the object, defaults to 'thread.message'."
-          default: "thread.message"
+          example: thread.message
         created_at:
           type: integer
           format: int64
@@ -22,7 +22,7 @@ components:
         assistant_id:
           type: string
           description: "Identifier of the assistant involved in the message. Defaults to parent thread."
-          example: "jan"
+          example: jan
         role:
           type: string
           enum: ["user", "assistant"]
@@ -41,25 +41,17 @@ components:
                   value:
                     type: string
                     description: "Text content of the message."
+                    example: "Hi!?"
                   annotations:
                     type: array
                     items:
                       type: string
                     description: "Annotations for the text content, if any."
+                    example: []
         metadata:
           type: object
           description: "Metadata associated with the message, defaults to an empty object."
-        chat_completion_id:
+          example: {}
-          type: string
-          description: "Identifier of the chat completion, if applicable."
-      required:
-        - id
-        - object
-        - created_at
-        - thread_id
-        - assistant_id
-        - role
-        - content
 
     GetMessageResponse:
       type: object
@@ -67,23 +59,24 @@ components:
         id:
           type: string
           description: "The identifier of the message."
-          example: "msg_abc123"
+          example: msg_abc123
         object:
           type: string
           description: "Type of the object, indicating it's a thread message."
-          default: "thread.message"
+          default: thread.message
         created_at:
           type: integer
           format: int64
           description: "Unix timestamp representing the creation time of the message."
+          example: 1699017614
         thread_id:
           type: string
           description: "Identifier of the thread to which this message belongs."
-          example: "thread_abc123"
+          example: thread_abc123
         role:
           type: string
           description: "Role of the sender, either 'user' or 'assistant'."
-          example: "user"
+          example: user
         content:
           type: array
           items:
@@ -92,6 +85,7 @@ components:
               type:
                 type: string
                 description: "Type of content, e.g., 'text'."
+                example: text
               text:
                 type: object
                 properties:
@@ -104,27 +98,25 @@ components:
                     items:
                       type: string
                     description: "Annotations for the text content, if any."
+                    example: []
         file_ids:
           type: array
           items:
             type: string
           description: "Array of file IDs associated with the message, if any."
+          example: []
         assistant_id:
           type: string
           description: "Identifier of the assistant involved in the message, if applicable."
+          example: null
         run_id:
           type: string
           description: "Run ID associated with the message, if applicable."
+          example: null
         metadata:
           type: object
           description: "Metadata associated with the message."
-      required:
+          example: {}
-        - id
-        - object
-        - created_at
-        - thread_id
-        - role
-        - content
 
     CreateMessageResponse:
       type: object
@@ -132,23 +124,24 @@ components:
         id:
           type: string
           description: "The identifier of the created message."
-          example: "msg_abc123"
+          example: msg_abc123
         object:
           type: string
           description: "Type of the object, indicating it's a thread message."
-          default: "thread.message"
+          example: thread.message
         created_at:
           type: integer
           format: int64
           description: "Unix timestamp representing the creation time of the message."
+          example: 1699017614
         thread_id:
           type: string
           description: "Identifier of the thread to which this message belongs."
-          example: "thread_abc123"
+          example: thread_abc123
         role:
           type: string
           description: "Role of the sender, either 'user' or 'assistant'."
-          example: "user"
+          example: user
         content:
           type: array
           items:
@@ -157,6 +150,7 @@ components:
               type:
                 type: string
                 description: "Type of content, e.g., 'text'."
+                example: text
               text:
                 type: object
                 properties:
@@ -169,27 +163,25 @@ components:
                     items:
                       type: string
                     description: "Annotations for the text content, if any."
+                    example: []
         file_ids:
           type: array
           items:
             type: string
           description: "Array of file IDs associated with the message, if any."
+          example: []
         assistant_id:
           type: string
           description: "Identifier of the assistant involved in the message, if applicable."
+          example: null
         run_id:
           type: string
           description: "Run ID associated with the message, if applicable."
+          example: null
         metadata:
           type: object
           description: "Metadata associated with the message."
-      required:
+          example: {}
-        - id
-        - object
-        - created_at
-        - thread_id
-        - role
-        - content
 
     ListMessagesResponse:
       type: object
@@ -214,12 +206,6 @@ components:
           type: boolean
           description: "Indicates whether there are more messages to retrieve."
           example: false
-      required:
-        - object
-        - data
-        - first_id
-        - last_id
-        - has_more
 
     ListMessageObject:
       type: object
@@ -227,23 +213,24 @@ components:
         id:
           type: string
           description: "The identifier of the message."
-          example: "msg_abc123"
+          example: msg_abc123
         object:
           type: string
           description: "Type of the object, indicating it's a thread message."
-          default: "thread.message"
+          example: thread.message
         created_at:
           type: integer
           format: int64
           description: "Unix timestamp representing the creation time of the message."
+          example: 1699017614
         thread_id:
           type: string
           description: "Identifier of the thread to which this message belongs."
-          example: "thread_abc123"
+          example: thread_abc123
         role:
           type: string
           description: "Role of the sender, either 'user' or 'assistant'."
-          example: "user"
+          example: user
         content:
           type: array
           items:
@@ -269,22 +256,19 @@ components:
           items:
             type: string
           description: "Array of file IDs associated with the message, if any."
+          example: []
         assistant_id:
           type: string
           description: "Identifier of the assistant involved in the message, if applicable."
+          example: null
         run_id:
           type: string
           description: "Run ID associated with the message, if applicable."
+          example: null
         metadata:
           type: object
           description: "Metadata associated with the message."
-      required:
+          example: {}
-        - id
-        - object
-        - created_at
-        - thread_id
-        - role
-        - content
 
     MessageFileObject:
       type: object
@@ -292,24 +276,21 @@ components:
         id:
           type: string
           description: "The identifier of the file."
-          example: "file-abc123"
+          example: file-abc123
         object:
           type: string
           description: "Type of the object, indicating it's a thread message file."
-          default: "thread.message.file"
+          example: thread.message.file
         created_at:
           type: integer
           format: int64
           description: "Unix timestamp representing the creation time of the file."
+          example: 1699061776
         message_id:
           type: string
           description: "Identifier of the message to which this file is associated."
-          example: "msg_abc123"
+          example: msg_abc123
-      required:
+
-        - id
-        - object
-        - created_at
-        - message_id
     ListMessageFilesResponse:
       type: object
       properties:
@@ -320,7 +301,4 @@ components:
         data:
           type: array
           items:
-            $ref: '#/components/schemas/MessageFileObject'
+            $ref: '#/components/schemas/MessageFileObject'
-      required:
-        - object
-        - data