From 015856104cad53c91be1b56b1fd2b03b78625851 Mon Sep 17 00:00:00 2001 From: hieu-jan <150573299+hieu-jan@users.noreply.github.com> Date: Thu, 23 Nov 2023 15:08:02 +0900 Subject: [PATCH] docs: update api reference messages --- docs/docs/specs/messages.md | 160 ++++++++++++++++++++++++++++++- docs/openapi/jan.yaml | 43 +++++---- docs/openapi/specs/messages.yaml | 110 +++++++++------------ 3 files changed, 230 insertions(+), 83 deletions(-) diff --git a/docs/docs/specs/messages.md b/docs/docs/specs/messages.md index bb1efb49f..db54f7782 100644 --- a/docs/docs/specs/messages.md +++ b/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" } -``` --> \ No newline at end of file +``` --> +### 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" +} \ No newline at end of file diff --git a/docs/openapi/jan.yaml b/docs/openapi/jan.yaml index cf2f8ed25..c1bd48143 100644 --- a/docs/openapi/jan.yaml +++ b/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 - description: Retrieves all messages from the specified thread. + summary: List messaages + 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 - description: Sends a new message to the specified thread. + summary: Create message + 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 \ - -H "Content-Type: application/json" \ - -d '{"role": "user", "content": "How does AI work? Explain it in simple terms."}' + 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." + }' /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} \ - -H "Content-Type: application/json" + curl {JAN_URL}/v1/threads/{thread_id}/messages/{message_id} \ + -H "Content-Type: application/json" /threads/{thread_id}/messages/{message_id}/files: get: operationId: listMessageFiles tags: - Messages - summary: message files - description: Retrieves a list of files associated with a specific message in a thread. + summary: List message files + 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 diff --git a/docs/openapi/specs/messages.yaml b/docs/openapi/specs/messages.yaml index a3dc74a0d..daa998767 100644 --- a/docs/openapi/specs/messages.yaml +++ b/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'." - default: "thread.message" + description: "Type of the object, defaults to '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: - type: string - description: "Identifier of the chat completion, if applicable." - required: - - id - - object - - created_at - - thread_id - - assistant_id - - role - - content + example: {} 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: - - id - - object - - created_at - - thread_id - - role - - content + example: {} 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: - - id - - object - - created_at - - thread_id - - role - - content + example: {} 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: - - id - - object - - created_at - - thread_id - - role - - content + example: {} 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" - required: - - id - - object - - created_at - - message_id + example: msg_abc123 + ListMessageFilesResponse: type: object properties: @@ -320,7 +301,4 @@ components: data: type: array items: - $ref: '#/components/schemas/MessageFileObject' - required: - - object - - data \ No newline at end of file + $ref: '#/components/schemas/MessageFileObject' \ No newline at end of file