OpenAI Files API: file inputs, search, and support knowledge

What the OpenAI Files API is for

The Files reference covers files uploaded to OpenAI and the file IDs returned by those uploads. A file ID can be used in different workflows. The two choices that matter most for support knowledge are direct file inputs and retrieval.

This distinction prevents a common design mistake: treating an upload endpoint as a complete knowledge system. The Files API stores a file. It does not know whether a refund policy is superseded, whether a customer has been verified, or whether a refund actually completed.

Choose direct inputs for a bounded file question

With file inputs, a Responses API request can include Base64 data, a file ID returned by the Files API, or an external file URL. This is useful when the question is specific: “Summarize this contract,” “extract the return deadline from this PDF,” or “compare these two approved policy drafts.”

For files that will be passed as model inputs, OpenAI documents user_data as the appropriate upload purpose. A request can contain more than one file, but the current input-file limits are 50 MB per file and 50 MB in total. Treat those as product constraints to recheck before you ship, not as a reason to split confidential material into smaller unreviewed uploads.

Format changes what the model sees:

• For PDFs sent to a vision-capable model, OpenAI processes extracted text and page images.
• For non-PDF documents, it extracts text only. Embedded diagrams and charts are not carried into context the same way.
• For spreadsheet inputs, OpenAI applies a spreadsheet-specific augmentation flow instead of simply placing every cell in context.

If a policy exception is in a scanned table or a chart, test that exact artifact. Do not assume a successful upload means the model saw the relevant value.

Use vector stores when knowledge must be searched repeatedly

For reusable knowledge, OpenAI's retrieval guide describes vector stores. When you add a file, OpenAI chunks, embeds, and indexes it. File Search can then retrieve relevant passages by semantic and keyword search when it is made available to a Responses API model.

The basic lifecycle is simple:

1. Create a vector store for a defined collection, such as approved support policies.
2. Upload the approved file and add it to that store.
3. Wait for the vector-store file to finish processing.
4. Search with representative customer questions, or let a Responses API request use File Search.
5. Inspect the passages and the final answer before you automate a reply.

OpenAI provides polling helpers such as uploadAndPoll and createAndPoll, because adding a vector-store file can take time. If you handle the status yourself, do not send a customer answer merely because the raw file upload completed.

The File Search guide also distinguishes retrieved citations from underlying search results. Decide what your support team needs to inspect: the source file, the retrieved passage, the answer, or all three. A support workflow with refunds or account changes usually needs more than a plausible answer.

Test knowledge quality, not just retrieval

Start with a small, versioned set of approved sources. Then build an evaluation set that includes:

• Straightforward questions that should find the policy.
• Questions that should trigger an exception or a handoff.
• Questions based on older wording that must not override the current policy.
• Questions that need customer-specific evidence the document cannot provide.

Record whether the right source appeared, whether the answer preserved the policy boundary, and whether the workflow routed uncertainty to a person. If you remove a file from a vector store, OpenAI notes that removal is eventually consistent: a search may still return its content briefly. Plan a transition and re-test rather than assuming a deletion is instant.

Control cost and retention deliberately

Vector-store cost is based on the total size of parsed chunks and their embeddings, not merely the source document's original file size. In the current retrieval pricing, the first 1 GB across vector stores is free and additional storage is listed at $0.10 per GB per day. Model usage and other tools can add separate costs.

That makes source hygiene an engineering and support task. Remove obsolete material on a deliberate schedule, but first verify that a replacement is processed and produces the intended result. Measure the full workflow with your actual documents and questions; a storage estimate alone does not reveal a poor answer, a missing handoff, or an unnecessary escalation.

Use eesel CLI to review support knowledge after a file changes

OpenAI's Files API is infrastructure for an application you build. eesel is a ready-to-work helpdesk teammate. The eesel CLI is another way to operate that teammate: from a terminal, a script, or a coding agent such as Claude Code, Codex, or Cursor. The teammate and workspace are the same as in the dashboard, so CLI changes appear there and dashboard changes appear in the CLI.

That is useful after a support lead revises a refund-policy PDF. The lead can ask a coding agent for an inspection report before any change: which sources are connected, whether their content is downloaded, what files were manually uploaded, and which instructions govern exceptions and human handoff. The coding agent reads JSON output; it should not connect accounts or change permissions while making that report.

Start with Node.js 18.17 or newer, sign in, and identify the intended teammate:

npx @eesel/cli login
npx @eesel/cli whoami
npx @eesel/cli agents

TARGET_EESEL_AGENT="paste-agent-id-or-name-here"

Use the explicit agent scope for every following command. It keeps a script or coding agent from acting on a saved default teammate by mistake:

npx @eesel/cli status --agent "$TARGET_EESEL_AGENT"
npx @eesel/cli integrations --agent "$TARGET_EESEL_AGENT"
npx @eesel/cli files ls --agent "$TARGET_EESEL_AGENT"
npx @eesel/cli instructions --agent "$TARGET_EESEL_AGENT"

After a human approves the policy file and its audience, preview the write before sending it. The CLI's --dry-run prints the server call without making it:

npx @eesel/cli files upload ./approved-refund-policy.pdf --agent "$TARGET_EESEL_AGENT" --dry-run
npx @eesel/cli files upload ./approved-refund-policy.pdf --agent "$TARGET_EESEL_AGENT"
npx @eesel/cli files ls --agent "$TARGET_EESEL_AGENT"

Then perform the approved upload, confirm the source is available, and use a new, named conversation for a redacted test. This chat is billed work; the inspection commands are free.

npx @eesel/cli new --name "refund-policy-file-check" --agent "$TARGET_EESEL_AGENT"
npx @eesel/cli chat "Using the approved refund policy, explain what evidence is required for a damaged item reported after the normal window. Do not promise a refund; state when a human must decide." --agent "$TARGET_EESEL_AGENT"

Review the answer against the approved policy, not just for fluent wording. Check that it asks for missing evidence, does not invent an exception, and gives an honest handoff. If the workflow creates a held action, inspect it with npx @eesel/cli approvals --agent "$TARGET_EESEL_AGENT". A reply is not proof that a refund, order update, or other external action happened; verify the final result in the connected system before telling the customer it did.

The Integrations view helps a support lead verify which sources are connected and added to the teammate before a controlled knowledge test.

When each approach fits

Choose the OpenAI Files API when you are building a custom application that needs to accept a document, pass it to a model, or create your own retrieval layer. You own the upload path, source authorization, vector-store design, evaluation, customer experience, and action verification.

Use eesel when your immediate job is to operate a helpdesk teammate that works with the knowledge sources and channels your support team already uses. Its CLI gives humans, scripts, and coding agents a careful way to inspect that same teammate and run an approved test from the terminal. It does not turn eesel into OpenAI's file storage or replace the checks your support process needs.

If you want to review support knowledge and policy behavior before customers rely on it, try eesel, then read the CLI guide.