Vector stores and file search

Purpose and Scope

File search is the OpenAI-hosted retrieval tool that lets a model consult uploaded documents while answering a request. A vector store is the knowledge-base container behind that tool: files are uploaded, processed, embedded, indexed, and then made available to Responses or Assistants workflows that declare a file_search tool. The important developer concern is not implementing semantic search locally, but wiring the hosted resource lifecycle correctly: create or select files, attach them to a vector store, wait for processing, and reference the store from the model workflow that should retrieve from it.

In this SDK, vector-store workflows are reached through the generated OpenAI client package rather than through a hand-written retrieval subsystem. The package entrypoint exports the default OpenAI client, the named OpenAI class, core promise and pagination helpers, upload helpers, and typed error classes. That matters for file search because the workflow combines several SDK capabilities: file upload, paginated resource listing, generated resource methods, and ordinary API error handling. Sources: src/index.ts

Relevant Source Files

• src/index.ts — package entrypoint that exports the default OpenAI client, named client type, upload helper types, pagination promise type, and SDK error classes used by generated resource calls.
• src/_vendor/zod-to-json-schema/index.ts — bundled schema conversion entrypoint. It is relevant when file-search workflows are combined with structured tool or response schemas in agent-style applications.
• src/internal/qs/index.ts — shared query-string formatter exports used by generated request code when list, pagination, and filter-style parameters need URL serialization.
• src/auth/index.ts — authentication helper exports for workload identity and token-provider based deployments that may run ingestion or retrieval jobs without long-lived local API keys.
• src/beta/realtime/index.ts — beta realtime error export. It is adjacent rather than central to file search, but relevant when retrieval-backed applications also include realtime sessions.
• src/realtime/index.ts — stable realtime error export for applications that combine retrieval setup with realtime interaction layers.

Core Concepts

A file-search application usually has two phases. The ingestion phase prepares the knowledge base by sending documents to the Files API and attaching them to a vector store. The serving phase sends model requests with a tool configuration that points at the store. OpenAI’s platform documentation describes this as a hosted tool: the model decides when to call the tool, OpenAI performs retrieval over the uploaded knowledge base, and the model uses the retrieved material in its answer. That design keeps parsing, chunking, embedding, keyword indexing, and ranking out of the application code path.

Embeddings are the mathematical foundation behind the semantic part of this workflow. OpenAI documentation defines an embedding as a vector of floating point numbers where distance between vectors measures relatedness. Search is one of the primary uses for embeddings, because a query and candidate document chunks can be compared by vector similarity. File search builds on that idea but packages it as a managed retrieval primitive. Instead of manually creating embeddings for every document, storing them, and writing ranking logic, the application delegates those operations to the vector store and file-search tool.

The term vector_store is therefore a resource concept, while file_search is a tool concept. The vector store persists and organizes searchable content. Vector store files and file batches represent the attachment and processing of files inside that store. The file-search tool is what a model request uses to retrieve from one or more stores. Keeping those terms separate helps when debugging: an upload problem belongs to file or vector-store ingestion, while an answer-quality or tool-use problem belongs to request configuration, store selection, or the content available for retrieval.

System-to-Code Mapping

The repository evidence for this page shows that the public package is organized around a generated SDK entrypoint. src/index.ts states that it is generated from the OpenAPI spec and exports OpenAI as the default client. It also re-exports Uploadable and toFile, which are important for document-ingestion paths because file search begins with uploadable file content before the files can be indexed into a vector store. The same entrypoint exposes PagePromise, which is the SDK-level signal that list-style generated methods may return paginated results. Sources: src/index.ts

Shared helpers support the generated API surface without becoming file-search-specific APIs. src/internal/qs/index.ts exports stringify and named query-string formats, giving generated methods a central way to serialize query parameters. That is relevant for vector store lists, file lists, batch lists, and similar collection endpoints because pagination cursors and filter parameters ultimately need consistent URL encoding. The page should be read as a workflow guide over those generated resources, not as a replacement for the generated method reference. Sources: src/internal/qs/index.ts

Some retrieval applications combine file search with structured outputs or tool schemas. The repository includes a vendored zod-to-json-schema entrypoint that re-exports parser modules and the default zodToJsonSchema converter. That helper is not itself a vector-store API, but it supports common agent patterns where a model retrieves evidence from files and then returns a validated structured object. In that design, vector stores supply relevant context, while JSON schema constrains the shape of the answer or tool arguments. Sources: src/_vendor/zod-to-json-schema/index.ts

Execution Flow

A typical TypeScript flow starts by creating an OpenAI client from the package entrypoint. The ingestion worker uploads one or more documents, creates or selects a vector store, and attaches the uploaded files to that store. For multiple files, file-batch operations are commonly used so that the application can treat a group of attachments as one processing job. The application should wait until files have left the processing state before relying on the store in production traffic; otherwise the model may search a partially indexed knowledge base and return incomplete answers.

After ingestion, the serving request enables file_search as a hosted tool and supplies the relevant vector store reference in the request or assistant configuration. The model can then decide whether retrieval is needed for a user question. This is different from sending embeddings manually: the application does not fetch nearest neighbors and paste them into the prompt. Instead, the request declares the tool boundary and lets the hosted service perform retrieval. That reduces local complexity, but it also makes resource hygiene important: stale, duplicated, or incorrectly scoped stores directly affect what the model can retrieve.

A compact Responses-style sketch looks like this:

import OpenAI from 'openai';
 
const client = new OpenAI();
 
// 1. Upload files with the Files API.
// 2. Add those files to a vector store and wait for processing.
// 3. Reference the vector store from a model request using the file_search tool.
const response = await client.responses.create({
  model: 'gpt-5.5',
  input: 'Answer using the product documentation knowledge base.',
  tools: [{ type: 'file_search', vector_store_ids: ['vs_...'] }],
});
 
console.log(response.output_text);

Treat the snippet as a workflow shape rather than a full reference. The exact generated parameter types should be checked in the SDK API reference for the version in use. The stable invariant is that file content is first represented as uploaded files, then indexed in vector stores, and finally made available to model requests through the file-search tool. The package entrypoint is the import boundary for that workflow, while the generated client resources provide the concrete methods. Sources: src/index.ts

Authentication and Deployment Considerations

Vector-store ingestion is often done by backend jobs, CI workflows, customer-specific importers, or scheduled data refresh processes. The SDK includes authentication exports for workload identity, subject token providers, and provider-specific token helpers such as Kubernetes service account, Azure managed identity, and Google Cloud ID token providers. Those exports are useful when retrieval infrastructure runs in managed cloud environments and should avoid embedding long-lived secrets in job configuration. Sources: src/auth/index.ts

The ingestion path should also be designed for retries, pagination, and observability. Large document sets can require listing files, checking batch status, and walking through paginated collections. Because the SDK exports API error classes from the main entrypoint, application code can distinguish authentication failures, rate limits, connection failures, not-found cases, and validation errors using the same error surface as other OpenAI API calls. That lets teams build a single operational policy for uploads, vector-store maintenance, and retrieval-serving requests. Sources: src/index.ts

Realtime modules are not required to create vector stores, but they matter in applications where retrieval-backed answers are delivered through realtime sessions. Both src/beta/realtime/index.ts and src/realtime/index.ts export OpenAIRealtimeError, giving realtime code a specific error type while the main package entrypoint covers regular REST API errors. If an application uses file search to prepare context and realtime to interact with users, keep the ingestion lifecycle and realtime session lifecycle separate so that indexing failures are not confused with session transport failures. Sources: src/beta/realtime/index.ts, src/realtime/index.ts

Practical Guidance and Next Steps

Use vector stores when you want the model to retrieve from a managed document knowledge base, especially when documents are larger or more numerous than you can safely include in every prompt. Use direct embeddings when you need to own the storage, ranking, or retrieval algorithm yourself. Use ordinary prompt context when the relevant information is small, static, and already known at request time. File search is strongest when the application needs repeatable retrieval over uploaded content without maintaining its own vector database.

For implementation, start with a small ingestion script before wiring retrieval into user traffic. Upload one representative file, add it to a vector store, wait for processing to complete, and ask a question whose answer is clearly present in the document. Then add batching, pagination, error handling, and deployment authentication. After the basic path works, read the Responses API, Files and uploads, Structured outputs, and Agents workflow pages to decide how retrieved evidence should be combined with tool calls, schemas, conversation state, or realtime user experiences.