Assistants API V2
https://platform.openai.com/docs/assistants/whats-new
Migrated SwiftOpenAI to assistants V2, if you need V1 support make sure to use v2.3
Check OpenAI migration guide.
We have changed the way that tools and files work in the Assistants API between the v1 and v2 versions of the beta. Both versions of the beta continue to be accessible via the API today, but we recommend migrating to the newest version of our APIs as soon as feasible. We will deprecate v1 of the beta by the end of 2024.
If you do not use tools or files with the Assistants API today, there should be no changes required for you to migrate from the v1 version to the v2 version of the beta. Simply pass the v2 beta version header and/or move to the latest version of our Node and Python SDKs!
What has changed
The v2 version of the Assistants API contains the following changes:
Tool rename: The retrieval tool has been renamed to the file_search tool
Files belong to tools: Files are now associated with tools instead of Assistants and Messages. This means that:
AssistantFile and MessageFile objects no longer exist.
Instead of AssistantFile and MessageFile, files are attached to Assistants and Threads using the new tool_resources object.
The tool_resources for the code interpreter tool are a list of file_ids.
The tool_resources for the file_search tool are a new object called a vector_stores.
Messages now have an attachments, rather than a file_ids parameter. Message attachments are helpers that add the files to a Thread’s tool_resources.
Assistants have tools and tool_resources instead of file_ids. The retrieval tool is now the file_search tool. The tool_resource for the file_search tool is a vector_store.
Threads can bring their own tool_resources into a conversation.
Messages have attachments instead of file_ids. attachments are helpers that add files to the Thread’s tool_resources.
All v1 endpoints and objects for the Assistants API can be found under the Legacy section of the API reference.
- Support for batch.
- Support for vector stores.
- Support for vector store files
- Support for vector store file batch.
New interfaces:
// MARK: Batch
/// Creates and executes a batch from an uploaded file of requests
///
/// - Parameter parameters: The parameters needed to create a batch.
/// - Returns: A [batch](https://platform.openai.com/docs/api-reference/batch/object) object.
/// - Throws: An error if the request fails
///
/// For more information, refer to [OpenAI's Batch API documentation](https://platform.openai.com/docs/api-reference/batch/create).
func createBatch(
parameters: BatchParameter)
async throws -> BatchObject
/// Retrieves a batch.
///
/// - Parameter id: The identifier of the batch to retrieve.
/// - Returns: A [BatchObject](https://platform.openai.com/docs/api-reference/batch/object) matching the specified ID..
/// - Throws: An error if the request fails.
///
/// For more information, refer to [OpenAI's Batch documentation](https://platform.openai.com/docs/api-reference/batch/retrieve).
func retrieveBatch(
id: String)
async throws -> BatchObject
/// Cancels an in-progress batch.
///
/// - Parameter id: The identifier of the batch to cancel.
/// - Returns: A [BatchObject](https://platform.openai.com/docs/api-reference/batch/object) matching the specified ID..
/// - Throws: An error if the request fails.
///
/// For more information, refer to [OpenAI's Batch documentation](https://platform.openai.com/docs/api-reference/batch/cancel)
func cancelBatch(
id: String)
async throws -> BatchObject
/// List your organization's batches.
///
/// - Parameters:
/// - after: 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.
/// - limit: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
/// - Returns: An `OpenAIResponse<BatchObject>` containing a list of paginated [Batch](https://platform.openai.com/docs/api-reference/batch/object) objects.
/// - Throws: An error if the request fails.
///
/// For more information, refer to [OpenAI's Batch API documentation](https://platform.openai.com/docs/api-reference/batch/list).
func listBatch(
after: String?,
limit: Int?)
async throws -> OpenAIResponse<BatchObject>
// MARK: Vector Store
/// Create a vector store.
///
/// - Parameter parameters: The parameters needed to create a batc,.
/// - Returns: A [Vector store](https://platform.openai.com/docs/api-reference/vector-stores) object.
/// - Throws: An error if the request fails
///
/// For more information, refer to [OpenAI's Vector store API documentation](https://platform.openai.com/docs/api-reference/vector-stores/create).
func createVectorStore(
parameters: VectorStoreParameter)
async throws -> VectorStoreObject
/// Returns a list of vector stores.
///
/// - Parameter limit: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
/// - Parameter order: Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.
/// - Parameter after: 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.
/// - Parameter before: 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 [VectorStoreObject](https://platform.openai.com/docs/api-reference/vector-stores) objects.
/// - Throws: An error if the request fails.
///
/// For more information, refer to [OpenAI's Vector stores API documentation](https://platform.openai.com/docs/api-reference/vector-stores/list).
func listVectorStores(
limit: Int?,
order: String?,
after: String?,
before: String?)
async throws -> OpenAIResponse<VectorStoreObject>
/// Retrieves a vector store.
///
/// - Parameter id: The ID of the vector store to retrieve.
/// - Returns: A [Vector Store](https://platform.openai.com/docs/api-reference/vector-stores) matching the specified ID..
/// - Throws: An error if the request fails.
///
/// For more information, refer to [OpenAI's Batch documentation](https://platform.openai.com/docs/api-reference/vector-stores/retrieve).
func retrieveVectorStore(
id: String)
async throws -> VectorStoreObject
/// Modifies a vector store.
///
/// - Parameter id: The ID of the vector store to modify.
/// - Returns: A [Vector Store](https://platform.openai.com/docs/api-reference/vector-stores) matching the specified ID..
/// - Throws: An error if the request fails.
///
/// For more information, refer to [OpenAI's Batch documentation](https://platform.openai.com/docs/api-reference/vector-stores/modify).
func modifyVectorStore(
id: String)
async throws -> VectorStoreObject
/// Delete a vector store.
///
/// - Parameter id: The ID of the vector store to delete.
/// - Returns: A Deletion status.
/// - Throws: An error if the request fails.
///
/// For more information, refer to [OpenAI's Batch documentation](https://platform.openai.com/docs/api-reference/vector-stores/modify).
func deleteVectorStore(
id: String)
async throws -> DeletionStatus
// MARK: Vector Store Files
/// Create a vector store file by attaching a [File](https://platform.openai.com/docs/api-reference/files) to a vector store.
///
/// - Parameter vectorStoreID: The ID of the vector store for which to create a File.
/// - Parameter parameters: The paramaters needed to create a vector store File.
/// - Returns: A [VectorStoreFileObject](https://platform.openai.com/docs/api-reference/vector-stores-files/file-object)
/// - Throws: An error if the request fails.
///
/// For more information, refer to [OpenAI's Vectore store file documentation.](https://platform.openai.com/docs/api-reference/vector-stores-files/createFile).
func createVectorStoreFile(
vectorStoreID: String,
parameters: VectorStoreFileParameter)
async throws -> VectorStoreFileObject
/// Returns a list of vector store files.
///
/// - Parameter vectorStoreID: The ID of the vector store that the files belong to.
/// - Parameter limit: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
/// - Parameter order: Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.
/// - Parameter after: 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.
/// - Parameter before: 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.
/// - Parameter filter: Filter by file status. One of `in_progress`, `completed`, `failed`, `cancelled`.
/// - Returns: A list of [VectorStoreFileObject](https://platform.openai.com/docs/api-reference/vector-stores-files/file-object) objects.
/// - Throws: An error if the request fails.
///
/// For more information, refer to [OpenAI's Vector stores API documentation](https://platform.openai.com/docs/api-reference/vector-stores-files/listFiles).
func listVectorStoreFiles(
vectorStoreID: String,
limit: Int?,
order: String?,
after: String?,
before: String?,
filter: String?)
async throws -> OpenAIResponse<VectorStoreFileObject>
/// Retrieves a vector store file.
///
/// - Parameter vectorStoreID: The ID of the vector store that the file belongs to.
/// - Parameter fileID: The ID of the file being retrieved.
/// - Returns: A [vector store file object](https://platform.openai.com/docs/api-reference/vector-stores-files/file-object)
/// - Throws: An error if the request fails.
///
/// For more information, refer to [OpenAI's Vector stores API documentation](https://platform.openai.com/docs/api-reference/vector-stores-files/getFile).
func retrieveVectorStoreFile(
vectorStoreID: String,
fileID: String)
async throws -> VectorStoreFileObject
/// Delete a vector store file. This will remove the file from the vector store but the file itself will not be deleted. To delete the file, use the [delete file](https://platform.openai.com/docs/api-reference/files/delete) endpoint.
///
/// - Parameter vectorStoreID: The ID of the vector store that the file belongs to.
/// - Parameter fileID: The ID of the file to delete.
/// - Returns: A deletion status.
/// - Throws: An error if the request fails.
///
/// For more information, refer to [OpenAI's Vector stores API documentation](https://platform.openai.com/docs/api-reference/vector-stores-files/deleteFile).
func deleteVectorStoreFile(
vectorStoreID: String,
fileID: String)
async throws -> DeletionStatus
// MARK: Vector Store File Batch
/// Create a vector store file batch.
///
/// - Parameter vectorStoreID: The ID of the vector store for which to create a File Batch.
/// - Parameter parameters: The paramaters needed to create a vector store File Batch.
/// - Returns: A [VectorStoreFileBatchObject](https://platform.openai.com/docs/api-reference/vector-stores-file-batches/batch-object)
/// - Throws: An error if the request fails.
///
/// For more information, refer to [OpenAI's Vectore store file batch documentation.](https://platform.openai.com/docs/api-reference/vector-stores-file-batches/createBatch).
func createVectorStoreFileBatch(
vectorStoreID: String,
parameters: VectorStoreFileBatchParameter)
async throws -> VectorStoreFileBatchObject
/// Retrieves a vector store file batch.
///
/// - Parameter vectorStoreID: The ID of the vector store that the file batch belongs to.
/// - Parameter batchID: The ID of the file batch being retrieved.
/// - Returns: A [vector store file batch object](https://platform.openai.com/docs/api-reference/vector-stores-file-batches/batch-object)
/// - Throws: An error if the request fails.
///
/// For more information, refer to [OpenAI's Vector stores file batch API documentation](https://platform.openai.com/docs/api-reference/vector-stores-file-batches/getBatch).
func retrieveVectorStoreFileBatch(
vectorStoreID: String,
batchID: String)
async throws -> VectorStoreFileBatchObject
/// Cancel a vector store file batch. This attempts to cancel the processing of files in this batch as soon as possible.
///
/// - Parameter vectorStoreID: The ID of the vector store that the file batch belongs to.
/// - Parameter batchID: The ID of the file batch to cancel.
/// - Returns: The modified [vector store file batch object.](https://platform.openai.com/docs/api-reference/vector-stores-file-batches/batch-object)
/// - Throws: An error if the request fails.
///
/// For more information, refer to [OpenAI's Vector stores file batch API documentation](https://platform.openai.com/docs/api-reference/vector-stores-file-batches/cancelBatch).
func cancelVectorStoreFileBatch(
vectorStoreID: String,
batchID: String)
async throws -> VectorStoreFileBatchObject
/// Returns a list of vector store files in a batch.
///
/// - Parameter vectorStoreID: The ID of the vector store that the files belong to.
/// - Parameter batchID: The ID of the file batch that the files belong to.
/// - Parameter limit: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
/// - Parameter order: Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.
/// - Parameter after: 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.
/// - Parameter before: 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.
/// - Parameter filter: Filter by file status. One of `in_progress`, `completed`, `failed`, `cancelled`.
/// - Returns: A list of [VectorStoreFileObject](https://platform.openai.com/docs/api-reference/vector-stores-files/file-object) objects in a batch.
/// - Throws: An error if the request fails.
///
/// For more information, refer to [OpenAI's Vector stores file batch API documentation](https://platform.openai.com/docs/api-reference/vector-stores-file-batches/listBatchFiles).
func listVectorStoreFilesInABatch(
vectorStoreID: String,
batchID: String,
limit: Int?,
order: String?,
after: String?,
before: String?,
filter: String?)
async throws -> OpenAIResponse<VectorStoreFileObject>