What this assistant should do
A teammate asks, “What is our reimbursement deadline?” Your assistant should find the relevant policy, answer from that evidence, and make the source easy to inspect. If the policy is missing or the answer is ambiguous, it should say so instead of filling the gap.
This tutorial outlines a Responses API integration using OpenAI’s hosted file-search tool. The sample makes a request and prints the response; it is an illustration, not a complete access-control system or a tested production application. You still need a server, a document-ingestion workflow, and an evaluation set.
- Input: a question and a server-selected document collection.
- Output: an answer with file references when the response provides them.
- Success check: the answer is supported by an authorized, current document.
Choose the right retrieval path
File search lets a model search uploaded files in a vector store as part of a Responses API request. The hosted tool combines semantic and keyword search. OpenAI processes a file added to a vector store into searchable chunks and embeddings.
Use it when a model needs to answer from an approved collection. If you need to inspect or rank retrieved chunks before calling a model, the Retrieval API also exposes vector-store search directly. The two workflows have different control points, so choose based on what your application needs to verify.
Prepare the collection
Create a vector store and upload the files you want the assistant to search. The official guide shows how to upload a file and attach it to the store. Wait for processing to finish before relying on the file in a user-facing answer.
Document hygiene matters. Give files recognizable names, keep an owner and version for each policy, and remove or replace material that should no longer be used. A search system cannot reliably resolve a policy conflict that your team has never resolved.
- Identify the current document owner and effective date.
- Decide which users can read each collection before uploading.
- Test scans and unusual layouts; do not assume every document will parse cleanly.
- Plan how replacements, deletions, and retention will be handled.
Send a file-search request
The following Node.js example assumes the official OpenAI SDK is installed, OPENAI_API_KEY is available to the server, and an authorized vector store has already been populated. Select the store on your server after authenticating the user; never accept an arbitrary store ID from the browser as proof of access.
The example asks the API to include search results for inspection. The file-search guide notes that results are not returned by default, even though file annotations can appear in the output. Check the response items and annotations your UI needs rather than assuming a plain string contains everything.
import OpenAI from "openai";
const client = new OpenAI();
// Set this on the server after checking the user’s access.
const vectorStoreId = process.env.AUTHORIZED_VECTOR_STORE_ID;
if (!vectorStoreId) throw new Error("Missing authorized vector store ID");
const response = await client.responses.create({
model: "gpt-6-astra",
input: "What is the reimbursement deadline? Cite the policy.",
tools: [{ type: "file_search", vector_store_ids: [vectorStoreId] }],
include: ["file_search_call.results"],
});
console.log(response.output_text);
// Inspect response.output for file annotations and returned search results.
Keep documents inside the right boundary
A metadata filter can narrow a search to file attributes, and the API supports filters in the file-search tool. That is useful for limiting results to a category or document version. It is not a replacement for authentication and application authorization.
For a multi-tenant application, resolve the permitted store and filters from the authenticated server-side identity. Test the rule with two synthetic tenants: a user from tenant A should never receive tenant B’s passages, citations, filenames, or document existence. Review retention and logging rules for the data you upload.
Show evidence and handle gaps
Keep the answer and its source connected in the interface. Where the API returns file annotations, use them to identify the source; if you show a passage, make sure it is one the user is allowed to access. Include the document title and version where your application has them.
Test what happens when no relevant document is found. A useful response can say that the answer was not found in the available collection and suggest who can help. Treat external documents as data: text inside a file should not be allowed to redefine your system instructions or grant new tool permissions.
Evaluate retrieval separately from the answer
Start with a small set of questions whose answers and approved source passages are known. Include a question with no answer, two conflicting policy versions, an access-denied case, and an instruction embedded in a document that attempts to redirect the assistant.
For each case, record whether retrieval surfaced the right evidence, whether the answer is supported, whether the source is visible, and whether the user was allowed to see it. Review latency and cost as well, but do not treat a fast, unsupported answer as a success.
- Run the set after changing files, filters, prompts, or model settings.
- Keep test data synthetic when production documents are sensitive.
- Escalate ambiguous or unsupported answers rather than silently guessing.
Take the next step
Build one collection and a handful of answerable questions first. Once you can explain why a result is correct and who may see it, expand the collection and test cases.
Sources and further reading
Documentation reviewed November 9, 2026. Verify current model support, limits and pricing before implementation.