Assistants API (Preview) messages reference
Note
- File search can ingest up to 10,000 files per assistant - 500 times more than before. It is fast, supports parallel queries through multi-threaded searches, and features enhanced reranking and query rewriting.
- Vector store is a new object in the API. Once a file is added to a vector store, it's automatically parsed, chunked, and embedded, made ready to be searched. Vector stores can be used across assistants and threads, simplifying file management and billing.
- We've added support for the
tool_choiceparameter which can be used to force the use of a specific tool (like file search, code interpreter, or a function) in a particular run.
This article provides reference documentation for Python and REST for the new Assistants API (Preview). More in-depth step-by-step guidance is provided in the getting started guide.
Create message
POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages?api-version=2024-05-01-preview
Create a message.
Path parameter
| Parameter | Type | Required | Description |
|---|---|---|---|
thread_id |
string | Required | The ID of the thread to create a message for. |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
role |
string | Required | The role of the entity that is creating the message. Can be user or assistant. user indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages. assistant indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation. |
content |
string | Required | The content of the message. |
file_ids |
array | Optional | A list of File IDs that the message should use. There can be a maximum of 10 files attached to a message. Useful for tools like retrieval and code_interpreter that can access and use files. |
metadata |
map | Optional | Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maximum of 512 characters long. |
Returns
A message object.
Example create message request
from openai import AzureOpenAI
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-05-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
thread_message = client.beta.threads.messages.create(
"thread_abc123",
role="user",
content="How does AI work? Explain it in simple terms.",
)
print(thread_message)
List messages
GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages?api-version=2024-05-01-preview
Returns a list of messages for a given thread.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
thread_id |
string | Required | The ID of the thread that messages belong to. |
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
limit |
integer | Optional - Defaults to 20 | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. |
order |
string | Optional - Defaults to desc | Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order. |
after |
string | Optional | A cursor for use in pagination. after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. |
before |
string | Optional | A cursor for use in pagination. before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. |
Returns
A list of message objects.
Example list messages request
from openai import AzureOpenAI
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-05-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
thread_messages = client.beta.threads.messages.list("thread_abc123")
print(thread_messages.data)
List message files
GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages/{message_id}/files?api-version=2024-05-01-preview
Returns a list of message files.
| Parameter | Type | Required | Description |
|---|---|---|---|
thread_id |
string | Required | The ID of the thread that the message and files belong to. |
message_id |
string | Required | The ID of the message that the files belong to. |
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
limit |
integer | Optional - Defaults to 20 | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. |
order |
string | Optional - Defaults to desc | Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order. |
after |
string | Optional | A cursor for use in pagination. after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. |
before |
string | Optional | A cursor for use in pagination. before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. |
Returns
A list of message file objects
Example list message files request
from openai import AzureOpenAI
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-05-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
message_files = client.beta.threads.messages.files.list(
thread_id="thread_abc123",
message_id="msg_abc123"
)
print(message_files)
Retrieve message
GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages/{message_id}?api-version=2024-05-01-preview
Retrieves a message file.
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
thread_id |
string | Required | The ID of the thread that the message belongs to. |
message_id |
string | Required | The ID of the message to retrieve. |
Returns
The message object matching the specified ID.
Example retrieve message request
from openai import AzureOpenAI
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-05-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
message = client.beta.threads.messages.retrieve(
message_id="msg_abc123",
thread_id="thread_abc123",
)
print(message)
Retrieve message file
GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages/{message_id}/files/{file_id}?api-version=2024-05-01-preview
Retrieves a message file.
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
thread_id |
string | Required | The ID of the thread, which the message and file belongs to. |
message_id |
string | Required | The ID of the message that the file belongs to. |
file_id |
string | Required | The ID of the file being retrieved. |
Returns
The message file object.
Example retrieve message file request
from openai import AzureOpenAI
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-05-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
message_files = client.beta.threads.messages.files.retrieve(
thread_id="thread_abc123",
message_id="msg_abc123",
file_id="assistant-abc123"
)
print(message_files)
Modify message
POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages/{message_id}?api-version=2024-05-01-preview
Modifies a message.
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
thread_id |
string | Required | The ID of the thread to which the message belongs. |
message_id |
string | Required | The ID of the message to modify. |
Request body
| Parameter | Type | Required | Description |
|---|---|---|---|
| metadata | map | Optional | Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maximum of 512 characters long. |
Returns
The modified message object.
from openai import AzureOpenAI
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-05-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
message = client.beta.threads.messages.update(
message_id="msg_abc12",
thread_id="thread_abc123",
metadata={
"modified": "true",
"user": "abc123",
},
)
print(message)
Message object
Represents a message within a thread.
| Name | Type | Description |
|---|---|---|
id |
string | The identifier, which can be referenced in API endpoints. |
object |
string | The object type, which is always thread.message. |
created_at |
integer | The Unix timestamp (in seconds) for when the message was created. |
thread_id |
string | The thread ID that this message belongs to. |
role |
string | The entity that produced the message. One of user or assistant. |
content |
array | The content of the message in array of text and/or images. |
assistant_id |
string or null | If applicable, the ID of the assistant that authored this message. |
run_id |
string or null | If applicable, the ID of the run associated with the authoring of this message. |
file_ids |
array | A list of file IDs that the assistant should use. Useful for tools like retrieval and code_interpreter that can access files. A maximum of 10 files can be attached to a message. |
metadata |
map | Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maximum of 512 characters long. |
Message file object
A list of files attached to a message.
| Name | Type | Description |
|---|---|---|
id |
string | The identifier, which can be referenced in API endpoints. |
object |
string | The object type, which is always thread.message.file. |
created_at |
integer | The Unix timestamp (in seconds) for when the message file was created. |
message_id |
string | The ID of the message that the File is attached to. |
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for