How to Manage Files with the OpenAI Assistants API

OpenAI categorizes file management into three distinct functional modes. Choosing the right mode depends on how you want the assistant to interact with the data. According to OpenAI documentation, these tools are not interchangeable and have different storage behaviors and cost structures.

File Search (Vector Stores) This mode is for information retrieval (RAG). Files are uploaded to a vector store, where they are automatically chunked and indexed. The assistant then performs a semantic search to find relevant context before generating a response. This is best for large knowledge bases, such as technical manuals or company policies.

Code Interpreter Code interpreter files are for data processing, analysis, and visualization. When you upload a file for this tool, the assistant can write and run Python code to read the file, create charts, or perform calculations. This is ideal for spreadsheets, CSVs, and image generation tasks.

Function Calling (External Files) While not a direct storage tool, function calling allows assistants to interact with files stored on external systems like Fast.io. Instead of uploading the file to OpenAI, you provide the assistant with a tool that can fetch or modify files in your own infrastructure. This is the preferred method for maintaining data sovereignty and persistent storage.

Helpful references: Fast.io Workspaces, Fast.io Collaboration, and Fast.io AI.

To use a file with an assistant, you must first upload it to the OpenAI Files API with a specific purpose. This is a critical step because files uploaded with the wrong purpose will not be accessible by the assistant tools.

When uploading via the API, you must set the purpose parameter to assistants. If you are using the Code Interpreter for a one-off analysis, you might also see the vision purpose for image files, but assistants is the standard for long-term document retrieval. Using the openai.files.create() method in Python or the equivalent REST endpoint is the standard way to initiate this.

Supported File Formats and Limits OpenAI supports a wide range of formats, including PDF, DOCX, TXT, and Markdown for file search. For code interpreter, it handles more technical formats like JSON, CSV, and XLSX.

• Maximum File Size: Large files (hundreds of MB).
• Token Limit: Each file can contain millions of tokens.
• Project Limit: Total storage per project is capped at 2.5 TB.

If your files exceed these limits, you should consider breaking them into smaller chunks or using an external storage provider that connects to the assistant via the Model Context Protocol (MCP).

Vector stores are the modern way to manage retrieval-augmented generation (RAG) within the Assistants API. A vector store acts as a container for your documents. When you add a file to a vector store, OpenAI takes care of the complex engineering work: parsing the document, splitting it into chunks, generating embeddings, and storing them in a searchable database.

Working with Vector Store Limits The Assistants API supports thousands of files per vector store. For most applications, this is plenty of room. However, managing these at scale requires automation. You should use the vector_store_batches endpoint to upload multiple files at once. This reduces API overhead and ensures that the indexing process happens in parallel.

Polling for Status After uploading, you must poll the status of the vector store file. The indexing process is not instantaneous. If you attempt to query the assistant before the file status is completed, the assistant will not be able to "see" the new information. Proper error handling at this stage prevents the "I don't have information on that" response from the model.

One of the powerful features of the Assistants API is the ability to attach files at different levels of the hierarchy. Understanding where to attach a file impacts both performance and cost.

Assistant-Level Files Files attached to the assistant itself are available to every thread and every user interacting with that assistant. These are typically global knowledge bases, like a product catalog or a set of brand guidelines. This is a persistent association that stays active until you manually remove the file or the vector store from the assistant's configuration.

Thread-Level Files For user-specific data, such as a customer's specific invoice or a personal document, you should attach the file to the thread. This ensures that the data is only accessible within that specific conversation. This pattern is essential for maintaining privacy in multi-tenant applications.

Managing the Context Window Every file you attach consumes a portion of the model's context window. If you attach too many files at the thread level, you may run into token limits or see a degradation in the assistant's ability to follow complex instructions. Strategic deletion of old thread-level files is necessary to keep the context clean and costs low.

Give Your AI Agents Persistent Storage

Stop managing ephemeral files. Get 50GB of free, persistent storage for your agents with 251 MCP tools and built-in RAG.

Sign Up Free

While OpenAI provides built-in storage, it is often ephemeral or locked into a single provider. For developers building production-grade agents, integrating with an intelligent workspace like Fast.io offers several advantages.

Fast.io provides persistent storage that isn't tied to a specific AI assistant session. By using the Fast.io MCP server, your agents gain access to 251 tools for managing files, workspaces, and sharing. This allows an agent to create a workspace, upload output files, and then transfer ownership of that workspace to a human teammate.

The MCP Advantage Using the Model Context Protocol (MCP) means your files are not stuck in an OpenAI silo. You can use the same file repository with Claude, Gemini, or local models. Fast.io also handles the RAG indexing automatically through its Intelligence Mode. When you enable this on a workspace, all files are auto-indexed and searchable by meaning, which saves you from having to manage OpenAI vector stores manually.

Ownership Transfer Workflow A common pattern for advanced agents is to work in a Fast.io workspace, organize research, and then generate a final report. Because Fast.io supports ownership transfer, the agent can hand over the entire project to a human client. The human gets a branded portal with all the files, while the agent retains the ability to update the data if needed.

Leaving files in the OpenAI cloud indefinitely leads to two problems: rising storage costs and "knowledge pollution." Old versions of documents can confuse the assistant if they aren't removed.

Automated Deletion Logic You should implement a cleanup script that runs periodically. This script should identify files that are no longer attached to active assistants or threads and delete them. This is especially important for the Code Interpreter, which often generates temporary files during execution. OpenAI does not automatically delete files when an assistant is deleted, so orphaned files can quickly accumulate.

Security and Access Control While Fast.io provides granular permissions and audit logs, the OpenAI Files API is relatively flat. Anyone with the API key can access any file. For sensitive data, you should use Fast.io to manage permissions and only provide the assistant with temporary, scoped access to the files it needs for a specific task.

Error Handling for Large Files When working with files near the 512MB limit, upload failures are more common. Always use chunked uploads and implement retry logic with exponential backoff. If a file consistently fails to index in a vector store, check for complex formatting issues in the PDF or unreadable characters in the text.