Files

List files

FileListPage files().list(FileListParamsparams = FileListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

get /files

Returns a list of files.

Parameters

FileListParams params
- Optional<String> after
  
  A cursor for use in pagination. after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.
- Optional<Long> limit
  
  A limit on the number of objects to be returned. Limit can range between 1 and 10,000, and the default is 10,000.
- Optional<Order> order
  
  Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.
  - ASC("asc")
  - DESC("desc")
- Optional<String> purpose
  
  Only return files with the given purpose.

Returns

class FileObject:

The File object represents a document that has been uploaded to OpenAI.
- String id
  
  The file identifier, which can be referenced in the API endpoints.
- long bytes
  
  The size of the file, in bytes.
- long createdAt
  
  The Unix timestamp (in seconds) for when the file was created.
- String filename
  
  The name of the file.
- JsonValue; object_ "file"constant
  
  The object type, which is always file.
  - FILE("file")
- Purpose purpose
  
  The intended purpose of the file. Supported values are assistants, assistants_output, batch, batch_output, fine-tune, fine-tune-results, vision, and user_data.
  - ASSISTANTS("assistants")
  - ASSISTANTS_OUTPUT("assistants_output")
  - BATCH("batch")
  - BATCH_OUTPUT("batch_output")
  - FINE_TUNE("fine-tune")
  - FINE_TUNE_RESULTS("fine-tune-results")
  - VISION("vision")
  - USER_DATA("user_data")
- Status status
  
  Deprecated. The current status of the file, which can be either uploaded, processed, or error.
  - UPLOADED("uploaded")
  - PROCESSED("processed")
  - ERROR("error")
- Optional<Long> expiresAt
  
  The Unix timestamp (in seconds) for when the file will expire.
- Optional<String> statusDetails
  
  Deprecated. For details on why a fine-tuning training file failed validation, see the error field on fine_tuning.job.

Example

package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.files.FileListPage;
import com.openai.models.files.FileListParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        FileListPage page = client.files().list();
    }
}

Response

{
  "data": [
    {
      "id": "id",
      "bytes": 0,
      "created_at": 0,
      "filename": "filename",
      "object": "file",
      "purpose": "assistants",
      "status": "uploaded",
      "expires_at": 0,
      "status_details": "status_details"
    }
  ],
  "first_id": "file-abc123",
  "has_more": false,
  "last_id": "file-abc456",
  "object": "list"
}

Upload file

FileObject files().create(FileCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())

post /files

Upload a file that can be used across various endpoints. Individual files can be up to 512 MB, and each project can store up to 2.5 TB of files in total. There is no organization-wide storage limit. Uploads to this endpoint are rate-limited to 1,000 requests per minute per authenticated user.

The Assistants API supports files up to 2 million tokens and of specific file types. See the Assistants Tools guide for details.
The Fine-tuning API only supports .jsonl files. The input also has certain required formats for fine-tuning chat or completions models.
The Batch API only supports .jsonl files up to 200 MB in size. The input also has a specific required format.
For Retrieval or file_search ingestion, upload files here first. If you need to attach multiple uploaded files to the same vector store, use /vector_stores/{vector_store_id}/file_batches instead of attaching them one by one. Vector store attachment has separate limits from file upload, including 2,000 attached files per minute per organization.

Please contact us if you need to increase these storage limits.

Parameters

FileCreateParams params
- String file
  
  The File object (not file name) to be uploaded.
- FilePurpose purpose
  
  The intended purpose of the uploaded file. One of:
  - assistants: Used in the Assistants API
  - batch: Used in the Batch API
  - fine-tune: Used for fine-tuning
  - vision: Images used for vision fine-tuning
  - user_data: Flexible file type for any purpose
  - evals: Used for eval data sets
- Optional<ExpiresAfter> expiresAfter
  
  The expiration policy for a file. By default, files with purpose=batch expire after 30 days and all other files are persisted until they are manually deleted.
  - JsonValue; anchor "created_at"constant
    
    Anchor timestamp after which the expiration policy applies. Supported anchors: created_at.
    - CREATED_AT("created_at")
  - long seconds
    
    The number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days).

Returns

class FileObject:

The File object represents a document that has been uploaded to OpenAI.
- String id
  
  The file identifier, which can be referenced in the API endpoints.
- long bytes
  
  The size of the file, in bytes.
- long createdAt
  
  The Unix timestamp (in seconds) for when the file was created.
- String filename
  
  The name of the file.
- JsonValue; object_ "file"constant
  
  The object type, which is always file.
  - FILE("file")
- Purpose purpose
  
  The intended purpose of the file. Supported values are assistants, assistants_output, batch, batch_output, fine-tune, fine-tune-results, vision, and user_data.
  - ASSISTANTS("assistants")
  - ASSISTANTS_OUTPUT("assistants_output")
  - BATCH("batch")
  - BATCH_OUTPUT("batch_output")
  - FINE_TUNE("fine-tune")
  - FINE_TUNE_RESULTS("fine-tune-results")
  - VISION("vision")
  - USER_DATA("user_data")
- Status status
  
  Deprecated. The current status of the file, which can be either uploaded, processed, or error.
  - UPLOADED("uploaded")
  - PROCESSED("processed")
  - ERROR("error")
- Optional<Long> expiresAt
  
  The Unix timestamp (in seconds) for when the file will expire.
- Optional<String> statusDetails
  
  Deprecated. For details on why a fine-tuning training file failed validation, see the error field on fine_tuning.job.

Example

package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.files.FileCreateParams;
import com.openai.models.files.FileObject;
import com.openai.models.files.FilePurpose;
import java.io.ByteArrayInputStream;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        FileCreateParams params = FileCreateParams.builder()
            .file(new ByteArrayInputStream("Example data".getBytes()))
            .purpose(FilePurpose.ASSISTANTS)
            .build();
        FileObject fileObject = client.files().create(params);
    }
}

Response

{
  "id": "id",
  "bytes": 0,
  "created_at": 0,
  "filename": "filename",
  "object": "file",
  "purpose": "assistants",
  "status": "uploaded",
  "expires_at": 0,
  "status_details": "status_details"
}

Delete file

FileDeleted files().delete(FileDeleteParamsparams = FileDeleteParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

delete /files/{file_id}

Delete a file and remove it from all vector stores.

Parameters

FileDeleteParams params
- Optional<String> fileId

Returns

class FileDeleted:
- String id
- boolean deleted
- JsonValue; object_ "file"constant
  - FILE("file")

Example

package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.files.FileDeleteParams;
import com.openai.models.files.FileDeleted;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        FileDeleted fileDeleted = client.files().delete("file_id");
    }
}

Response

{
  "id": "id",
  "deleted": true,
  "object": "file"
}

Retrieve file

FileObject files().retrieve(FileRetrieveParamsparams = FileRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

get /files/{file_id}

Returns information about a specific file.

Parameters

FileRetrieveParams params
- Optional<String> fileId

Returns

class FileObject:

The File object represents a document that has been uploaded to OpenAI.
- String id
  
  The file identifier, which can be referenced in the API endpoints.
- long bytes
  
  The size of the file, in bytes.
- long createdAt
  
  The Unix timestamp (in seconds) for when the file was created.
- String filename
  
  The name of the file.
- JsonValue; object_ "file"constant
  
  The object type, which is always file.
  - FILE("file")
- Purpose purpose
  
  The intended purpose of the file. Supported values are assistants, assistants_output, batch, batch_output, fine-tune, fine-tune-results, vision, and user_data.
  - ASSISTANTS("assistants")
  - ASSISTANTS_OUTPUT("assistants_output")
  - BATCH("batch")
  - BATCH_OUTPUT("batch_output")
  - FINE_TUNE("fine-tune")
  - FINE_TUNE_RESULTS("fine-tune-results")
  - VISION("vision")
  - USER_DATA("user_data")
- Status status
  
  Deprecated. The current status of the file, which can be either uploaded, processed, or error.
  - UPLOADED("uploaded")
  - PROCESSED("processed")
  - ERROR("error")
- Optional<Long> expiresAt
  
  The Unix timestamp (in seconds) for when the file will expire.
- Optional<String> statusDetails
  
  Deprecated. For details on why a fine-tuning training file failed validation, see the error field on fine_tuning.job.

Example

package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.files.FileObject;
import com.openai.models.files.FileRetrieveParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        FileObject fileObject = client.files().retrieve("file_id");
    }
}

Response

{
  "id": "id",
  "bytes": 0,
  "created_at": 0,
  "filename": "filename",
  "object": "file",
  "purpose": "assistants",
  "status": "uploaded",
  "expires_at": 0,
  "status_details": "status_details"
}

Retrieve file content

HttpResponse files().content(FileContentParamsparams = FileContentParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

get /files/{file_id}/content

Returns the contents of the specified file.

Parameters

FileContentParams params
- Optional<String> fileId

Example

package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.http.HttpResponse;
import com.openai.models.files.FileContentParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        HttpResponse response = client.files().content("file_id");
    }
}

Domain Types

File Deleted

class FileDeleted:
- String id
- boolean deleted
- JsonValue; object_ "file"constant
  - FILE("file")

File Object

class FileObject:

The File object represents a document that has been uploaded to OpenAI.
- String id
  
  The file identifier, which can be referenced in the API endpoints.
- long bytes
  
  The size of the file, in bytes.
- long createdAt
  
  The Unix timestamp (in seconds) for when the file was created.
- String filename
  
  The name of the file.
- JsonValue; object_ "file"constant
  
  The object type, which is always file.
  - FILE("file")
- Purpose purpose
  
  The intended purpose of the file. Supported values are assistants, assistants_output, batch, batch_output, fine-tune, fine-tune-results, vision, and user_data.
  - ASSISTANTS("assistants")
  - ASSISTANTS_OUTPUT("assistants_output")
  - BATCH("batch")
  - BATCH_OUTPUT("batch_output")
  - FINE_TUNE("fine-tune")
  - FINE_TUNE_RESULTS("fine-tune-results")
  - VISION("vision")
  - USER_DATA("user_data")
- Status status
  
  Deprecated. The current status of the file, which can be either uploaded, processed, or error.
  - UPLOADED("uploaded")
  - PROCESSED("processed")
  - ERROR("error")
- Optional<Long> expiresAt
  
  The Unix timestamp (in seconds) for when the file will expire.
- Optional<String> statusDetails
  
  Deprecated. For details on why a fine-tuning training file failed validation, see the error field on fine_tuning.job.

File Purpose

enum FilePurpose:

The intended purpose of the uploaded file. One of:
- assistants: Used in the Assistants API
- batch: Used in the Batch API
- fine-tune: Used for fine-tuning
- vision: Images used for vision fine-tuning
- user_data: Flexible file type for any purpose
- evals: Used for eval data sets
- ASSISTANTS("assistants")
- BATCH("batch")
- FINE_TUNE("fine-tune")
- VISION("vision")
- USER_DATA("user_data")
- EVALS("evals")

java/resources/files/index.md +63 −10

6 6

7**get** `/files`7**get** `/files`

8 8

~~9List files~~9Returns a list of files.

10 10

11### Parameters11### Parameters

12 12

149 149

150**post** `/files`150**post** `/files`

151 151

152Upload file152Upload a file that can be used across various endpoints. Individual files

153can be up to 512 MB, and each project can store up to 2.5 TB of files in

154total. There is no organization-wide storage limit. Uploads to this

155endpoint are rate-limited to 1,000 requests per minute per authenticated

156user.

157

158- The Assistants API supports files up to 2 million tokens and of specific

159 file types. See the [Assistants Tools guide](https://platform.openai.com/docs/assistants/tools) for

160 details.

161- The Fine-tuning API only supports `.jsonl` files. The input also has

162 certain required formats for fine-tuning

163 [chat](https://platform.openai.com/docs/api-reference/fine-tuning/chat-input) or

164 [completions](https://platform.openai.com/docs/api-reference/fine-tuning/completions-input) models.

165- The Batch API only supports `.jsonl` files up to 200 MB in size. The input

166 also has a specific required

167 [format](https://platform.openai.com/docs/api-reference/batch/request-input).

168- For Retrieval or `file_search` ingestion, upload files here first. If

169 you need to attach multiple uploaded files to the same vector store, use

170 [`/vector_stores/{vector_store_id}/file_batches`](https://platform.openai.com/docs/api-reference/vector-stores-file-batches/createBatch)

171 instead of attaching them one by one. Vector store attachment has separate

172 limits from file upload, including 2,000 attached files per minute per

173 organization.

174

175Please [contact us](https://help.openai.com/) if you need to increase these

176storage limits.

153 177

154### Parameters178### Parameters

155 179

159 183

160 The File object (not file name) to be uploaded.184 The File object (not file name) to be uploaded.

161 185

162 - `JsonValue purpose`186 - `FilePurpose purpose`

187

188 The intended purpose of the uploaded file. One of:

189

190 - `assistants`: Used in the Assistants API

191 - `batch`: Used in the Batch API

192 - `fine-tune`: Used for fine-tuning

193 - `vision`: Images used for vision fine-tuning

194 - `user_data`: Flexible file type for any purpose

195 - `evals`: Used for eval data sets

163 196

164 - `Optional<ExpiresAfter> expiresAfter`197 - `Optional<ExpiresAfter> expiresAfter`

165 198

248 281

249import com.openai.client.OpenAIClient;282import com.openai.client.OpenAIClient;

250import com.openai.client.okhttp.OpenAIOkHttpClient;283import com.openai.client.okhttp.OpenAIOkHttpClient;

251import com.openai.core.JsonValue;

252import com.openai.models.files.FileCreateParams;284import com.openai.models.files.FileCreateParams;

253import com.openai.models.files.FileObject;285import com.openai.models.files.FileObject;

286import com.openai.models.files.FilePurpose;

254import java.io.ByteArrayInputStream;287import java.io.ByteArrayInputStream;

255import java.util.Map;

256 288

257public final class Main {289public final class Main {

258 private Main() {}290 private Main() {}

262 294

263 FileCreateParams params = FileCreateParams.builder()295 FileCreateParams params = FileCreateParams.builder()

264 .file(new ByteArrayInputStream("Example data".getBytes()))296 .file(new ByteArrayInputStream("Example data".getBytes()))

265 .purpose(JsonValue.from(<String, Object>Map.of()))297 .purpose(FilePurpose.ASSISTANTS)

266 .build();298 .build();

267 FileObject fileObject = client.files().create(params);299 FileObject fileObject = client.files().create(params);

268 }300 }

291 323

292**delete** `/files/{file_id}`324**delete** `/files/{file_id}`

293 325

294Delete file326Delete a file and remove it from all vector stores.

295 327

296### Parameters328### Parameters

297 329

348 380

349**get** `/files/{file_id}`381**get** `/files/{file_id}`

350 382

351Retrieve file383Returns information about a specific file.

352 384

353### Parameters385### Parameters

354 386

465 497

466**get** `/files/{file_id}/content`498**get** `/files/{file_id}/content`

467 499

468Retrieve file content500Returns the contents of the specified file.

469 501

470### Parameters502### Parameters

471 503

576 608

577### File Purpose609### File Purpose

578 610

579- `class FilePurpose:`611- `enum FilePurpose:`

612

613 The intended purpose of the uploaded file. One of:

614

615 - `assistants`: Used in the Assistants API

616 - `batch`: Used in the Batch API

617 - `fine-tune`: Used for fine-tuning

618 - `vision`: Images used for vision fine-tuning

619 - `user_data`: Flexible file type for any purpose

620 - `evals`: Used for eval data sets

621

622 - `ASSISTANTS("assistants")`

623

624 - `BATCH("batch")`

625

626 - `FINE_TUNE("fine-tune")`

627

628 - `VISION("vision")`

629

630 - `USER_DATA("user_data")`

631

632 - `EVALS("evals")`

java/resources/files/index.md 2026-07-10 23:02 UTC to 2026-07-12 06:58 UTC

Files

List files

Parameters

Returns

Example

Response

Upload file

Parameters

Returns

Example

Response

Delete file

Parameters

Returns

Example

Response

Retrieve file

Parameters

Returns

Example

Response

Retrieve file content

Parameters

Example

Domain Types

File Deleted

File Object

File Purpose