Assistants API (Preview) threads reference

  • Article

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_choice parameter 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 a thread

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads?api-version=2024-08-01-preview

Create a thread.

Request body

Name Type Required Description
messages array Optional A list of messages to start the thread with.
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.
tool_resources object Optional A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the code_interpreter tool requires a list of file IDs, while the file_search tool requires a list of vector store IDs.

tool_resources properties

code_interpreter

Name Type Description Default
file_ids array A list of file IDs made available to the code_interpreter tool. There can be a maximum of 20 files associated with the tool. []

file_search

Name Type Description Default
vector_store_ids array The vector store attached to this thread. There can be a maximum of 1 vector store attached to the thread. []
vector_stores array A helper to create a vector store with file_ids and attach it to this thread. There can be a maximum of 1 vector store attached to the thread. []

Returns

A thread object.

Example: create thread request

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

empty_thread = client.beta.threads.create()
print(empty_thread)

Retrieve thread

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}?api-version=2024-08-01-preview

Retrieves a thread.

Path parameters

Parameter Type Required Description
thread_id string Required The ID of the thread to retrieve

Returns

The thread object matching the specified ID.

Example: retrieve thread request

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

my_thread = client.beta.threads.retrieve("thread_abc123")
print(my_thread)

Modify thread

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}?api-version=2024-08-01-preview

Modifies a thread.

Path Parameters

Parameter Type Required Description
thread_id string Required The ID of the thread to modify.

Request body

Name 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.
tool_resources object Optional A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the code_interpreter tool requires a list of file IDs, while the file_search tool requires a list of vector store IDs.

Returns

The modified thread object matching the specified ID.

Example: modify thread request

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

my_updated_thread = client.beta.threads.update(
  "thread_abc123",
  metadata={
    "modified": "true",
    "user": "abc123"
  }
)
print(my_updated_thread)

Delete thread

DELETE https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}?api-version=2024-05-01-preview

Delete a thread.

Path Parameters

Parameter Type Required Description
thread_id string Required The ID of the thread to delete.

Returns

Deletion status.

Example: delete thread 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")
    )

response = client.beta.threads.delete("thread_abc123")
print(response)

Thread object

Field Type Description
id string The identifier, which can be referenced in API endpoints.
object string The object type, which is always thread.
created_at integer The Unix timestamp (in seconds) for when the thread was created.
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.