Files and uploads reference

Purpose and Scope

This page is a method-level reference for the SDK surfaces that move file bytes into and out of the OpenAI API. In this SDK, the File API is the durable file object surface: you create a file with a purpose, retrieve metadata, list project files, delete a file, and fetch its binary content. The Uploads API is the resumable or staged upload surface: you create an upload record, add upload parts through the exported parts namespace, complete the upload with ordered part IDs, or cancel the upload if it should not be finalized.

The distinction matters when you design workflows for file search, Assistants, fine-tuning, batches, Code Interpreter, or GPT Actions. A file object is what downstream APIs usually reference after upload. An upload object, by contrast, is an intermediate assembly process for bytes and parts. The official platform guidance for file search starts by uploading a file to the File API before adding it to a vector store, while GPT Actions may pass file references to external APIs as short-lived download URLs. The SDK keeps those concerns separate so application code can choose the right lifecycle for the task.

Sources: src/resources/files.ts, src/resources/uploads/index.ts, tests/api-resources/uploads/uploads.test.ts

Relevant Source Files

• api.md — The generated public API reference for the package; use it as the exhaustive method and type index when you need every overload and generated request or response interface.
• src/resources/files.ts — Implements the Files resource, including create, retrieve, list, delete, content retrieval, multipart request handling, pagination, binary response handling, and file-processing helpers.
• src/resources/uploads/index.ts — Re-exports the Uploads resource, the upload Parts resource, and the generated Upload, UploadCreateParams, UploadCompleteParams, UploadPart, and PartCreateParams types.
• tests/api-resources/uploads/uploads.test.ts — Exercises the public client.uploads methods for create, complete, and cancel, including raw response access through asResponse() and paired data/response access through withResponse().

API Components

The primary entry points are available from an OpenAI client instance. File methods live under client.files, and upload methods live under client.uploads. The Files implementation extends the SDK’s generated APIResource base, uses APIPromise for asynchronous results, and applies bearer authentication to each request. File listing returns a PagePromise over a cursor-paginated page of file objects, so callers can use the SDK’s normal pagination patterns instead of manually passing cursors for every page.

Sources: src/resources/files.ts, api.md

The client.files.create() method sends multipart form data to the /files endpoint. Its request body is represented by FileCreateParams, and the important fields are the uploadable file value and the file purpose. The implementation wraps the request with multipartFormRequestOptions, which is the SDK’s internal path for converting uploadable inputs into a multipart request. That means application code should pass a supported uploadable value rather than trying to manually construct the HTTP request body when using the SDK.

Sources: src/resources/files.ts

The client.files.retrieve(fileID) and client.files.delete(fileID) methods both address a specific file by ID. Retrieval returns file metadata; deletion removes the file and, according to the generated resource comment, removes it from all vector stores. This behavior is important for cleanup routines because deleting a file is not just a local metadata operation. If your application uses vector stores for file search, deletion can affect search-backed workflows that previously referenced that file.

Sources: src/resources/files.ts

The client.files.content(fileID) method is the binary content retrieval endpoint. Its implementation sets an Accept header for application/binary and marks the response as a binary response, returning an APIPromise<Response> rather than directly parsing JSON. Treat this method differently from metadata retrieval: after awaiting the response, consume the platform Response object with the binary reader that fits your runtime, such as arrayBuffer(), blob(), or a stream-compatible path when available.

Sources: src/resources/files.ts

The Uploads namespace is separate from the Files namespace. The source barrel exports Uploads and Parts, along with generated types for upload creation, completion, upload parts, and part creation parameters. The resource tests show client.uploads.create(), client.uploads.complete(), and client.uploads.cancel() as public methods. They also verify that these methods return the SDK’s promise wrapper, which can be awaited for parsed data, converted to a raw Response with asResponse(), or used with withResponse() when code needs both parsed data and HTTP response metadata.

Sources: src/resources/uploads/index.ts, tests/api-resources/uploads/uploads.test.ts

Method Reference

A typical File API call is compact because the SDK owns multipart encoding. For local files in Node.js, pass an uploadable file value and the correct API purpose. Purposes are not interchangeable: fine-tuning expects .jsonl files in fine-tuning formats, batch input is also .jsonl with its own size and request format constraints, and retrieval or file_search workflows upload through the File API before vector-store attachment. The generated comments also record operational limits, including individual file size, project storage, request-rate limits, and separate vector-store attachment limits.

Sources: src/resources/files.ts

import fs from 'fs';
import OpenAI from 'openai';
 
const client = new OpenAI();
 
const file = await client.files.create({
  file: fs.createReadStream('knowledge.pdf'),
  purpose: 'assistants',
});
 
console.log(file.id);

For staged uploads, the flow is create, add parts, complete. The upload creation test shows the required creation fields: bytes, filename, mime_type, and purpose. It also shows expires_after as an optional object with anchor: 'created_at' and seconds. Completion requires part_ids, and may include an md5 checksum. Cancellation only needs the upload ID. This shape is useful when an application already knows the total byte count and wants explicit control over the assembly lifecycle instead of sending a single multipart file request.

Sources: tests/api-resources/uploads/uploads.test.ts, src/resources/uploads/index.ts

const upload = await client.uploads.create({
  bytes: 1024,
  filename: 'dataset.jsonl',
  mime_type: 'application/jsonl',
  purpose: 'fine-tune',
  expires_after: { anchor: 'created_at', seconds: 3600 },
});
 
// Create upload parts through the generated parts namespace, then complete:
const completed = await client.uploads.complete(upload.id, {
  part_ids: ['part_1', 'part_2'],
  md5: 'optional-md5-checksum',
});

Execution Flow and Runtime Behavior

When you call a File API method, the SDK constructs the REST path and applies request options in the same generated style used across the package. Path interpolation is handled by the internal path utility, authentication is attached through the request security configuration, and per-call RequestOptions can be merged into the request. For binary file content, the implementation explicitly changes the accepted response format rather than treating the endpoint like a JSON API. That is why content retrieval should be handled as HTTP response data, while file metadata calls can be treated as typed objects.

Sources: src/resources/files.ts

Pagination is another important runtime difference. client.files.list() returns a cursor-page promise, not a raw array. This matches the API’s list-resource pattern and allows consumers to iterate across pages using SDK pagination helpers. If you are building an administrative file browser, a cleanup job, or a migration script, use the paginated abstraction rather than assuming all files fit into one response. The query parameter type is FileListParams, so filters supported by the generated API reference should be passed as a query object.

Sources: src/resources/files.ts, api.md

The upload tests demonstrate the SDK promise contract. Each upload method returns an object that can be awaited for parsed data, but the same promise can expose the raw Response through asResponse() before parsing, or return { data, response } through withResponse(). That pattern is especially helpful for upload orchestration because callers may need response headers, status codes, or request diagnostics when debugging partial upload failures, checksum mismatches, or cancellation behavior.

Sources: tests/api-resources/uploads/uploads.test.ts

Integration Notes

Files are often only the first step in a larger workflow. For file search, upload the source document through client.files.create(), then attach the resulting file to a vector store or file batch using the vector-store resources. The official file-search guidance frames file search as a hosted tool: after files are uploaded and indexed, the model can retrieve relevant information without the application implementing semantic search execution. The SDK’s file upload surface therefore supplies the durable file ID that other resources consume.

GPT Actions introduce a different file-reference pattern. When actions send files to an external API, the action request may include openaiFileIdRefs, where each item contains a name, stable file ID, MIME type, and a short-lived download link. That is not the same as fetching client.files.content() inside your application. Use SDK file content retrieval when your application is the consumer of the bytes, and use the action file-reference contract when the model-driven action call is passing user, generated, or Code Interpreter files to your OpenAPI-backed service.

Sources: src/resources/files.ts, api.md

Testing Signals and Next Steps

The upload resource tests are useful examples because they validate the public method names and response helper behavior without depending on live OpenAI services. They configure an OpenAI client with a test base URL, call client.uploads.create(), client.uploads.complete(), and client.uploads.cancel(), and confirm that the SDK promise can produce both parsed data and the underlying Response. If you are adding upload orchestration code, mirror that style in application tests by asserting both successful data parsing and the HTTP metadata you depend on.

Sources: tests/api-resources/uploads/uploads.test.ts

For implementation work, start with the simpler File API when the file can be sent as a single uploadable value and you only need the resulting file ID. Use the Uploads API when your workflow requires an upload record, explicit parts, completion with ordered part IDs, or cancellation before finalization. After the file exists, continue to the vector stores and file search pages for retrieval workflows, the fine-tuning reference for training data, or the batch reference for offline request processing.