Files

List files

files.list(**kwargs) -> CursorPage<FileObject>

get /files

Returns a list of files.

Parameters

after: String

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.
limit: Integer

A limit on the number of objects to be returned. Limit can range between 1 and 10,000, and the default is 10,000.
order: :asc | :desc

Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.
- :asc
- :desc
purpose: String

Only return files with the given purpose.

Returns

class FileObject

The File object represents a document that has been uploaded to OpenAI.
- id: String
  
  The file identifier, which can be referenced in the API endpoints.
- bytes: Integer
  
  The size of the file, in bytes.
- created_at: Integer
  
  The Unix timestamp (in seconds) for when the file was created.
- filename: String
  
  The name of the file.
- object: :file
  
  The object type, which is always file.
  - :file
- purpose: :assistants | :assistants_output | :batch | 5 more
  
  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_output
  - :batch
  - :batch_output
  - :"fine-tune"
  - :"fine-tune-results"
  - :vision
  - :user_data
- status: :uploaded | :processed | :error
  
  Deprecated. The current status of the file, which can be either uploaded, processed, or error.
  - :uploaded
  - :processed
  - :error
- expires_at: Integer
  
  The Unix timestamp (in seconds) for when the file will expire.
- status_details: String
  
  Deprecated. For details on why a fine-tuning training file failed validation, see the error field on fine_tuning.job.

Example

require "openai"

openai = OpenAI::Client.new(api_key: "My API Key")

page = openai.files.list

puts(page)

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

files.create(**kwargs) -> FileObject

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

file: String

The File object (not file name) to be uploaded.
purpose: 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
- :batch
- :"fine-tune"
- :vision
- :user_data
- :evals
expires_after: ExpiresAfter{ anchor, seconds}

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.
- anchor: :created_at
  
  Anchor timestamp after which the expiration policy applies. Supported anchors: created_at.
  - :created_at
- seconds: Integer
  
  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.
- id: String
  
  The file identifier, which can be referenced in the API endpoints.
- bytes: Integer
  
  The size of the file, in bytes.
- created_at: Integer
  
  The Unix timestamp (in seconds) for when the file was created.
- filename: String
  
  The name of the file.
- object: :file
  
  The object type, which is always file.
  - :file
- purpose: :assistants | :assistants_output | :batch | 5 more
  
  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_output
  - :batch
  - :batch_output
  - :"fine-tune"
  - :"fine-tune-results"
  - :vision
  - :user_data
- status: :uploaded | :processed | :error
  
  Deprecated. The current status of the file, which can be either uploaded, processed, or error.
  - :uploaded
  - :processed
  - :error
- expires_at: Integer
  
  The Unix timestamp (in seconds) for when the file will expire.
- status_details: String
  
  Deprecated. For details on why a fine-tuning training file failed validation, see the error field on fine_tuning.job.

Example

require "openai"

openai = OpenAI::Client.new(api_key: "My API Key")

file_object = openai.files.create(file: StringIO.new("Example data"), purpose: :assistants)

puts(file_object)

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

files.delete(file_id) -> FileDeleted

delete /files/{file_id}

Delete a file and remove it from all vector stores.

Parameters

file_id: String

Returns

class FileDeleted
- id: String
- deleted: bool
- object: :file
  - :file

Example

require "openai"

openai = OpenAI::Client.new(api_key: "My API Key")

file_deleted = openai.files.delete("file_id")

puts(file_deleted)

Response

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

Retrieve file

files.retrieve(file_id) -> FileObject

get /files/{file_id}

Returns information about a specific file.

Parameters

file_id: String

Returns

class FileObject

The File object represents a document that has been uploaded to OpenAI.
- id: String
  
  The file identifier, which can be referenced in the API endpoints.
- bytes: Integer
  
  The size of the file, in bytes.
- created_at: Integer
  
  The Unix timestamp (in seconds) for when the file was created.
- filename: String
  
  The name of the file.
- object: :file
  
  The object type, which is always file.
  - :file
- purpose: :assistants | :assistants_output | :batch | 5 more
  
  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_output
  - :batch
  - :batch_output
  - :"fine-tune"
  - :"fine-tune-results"
  - :vision
  - :user_data
- status: :uploaded | :processed | :error
  
  Deprecated. The current status of the file, which can be either uploaded, processed, or error.
  - :uploaded
  - :processed
  - :error
- expires_at: Integer
  
  The Unix timestamp (in seconds) for when the file will expire.
- status_details: String
  
  Deprecated. For details on why a fine-tuning training file failed validation, see the error field on fine_tuning.job.

Example

require "openai"

openai = OpenAI::Client.new(api_key: "My API Key")

file_object = openai.files.retrieve("file_id")

puts(file_object)

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

files.content(file_id) -> StringIO

get /files/{file_id}/content

Returns the contents of the specified file.

Parameters

file_id: String

Returns

StringIO

Example

require "openai"

openai = OpenAI::Client.new(api_key: "My API Key")

response = openai.files.content("file_id")

puts(response)

Domain Types

File Content

FileContent = String

File Deleted

class FileDeleted
- id: String
- deleted: bool
- object: :file
  - :file

File Object

class FileObject

The File object represents a document that has been uploaded to OpenAI.
- id: String
  
  The file identifier, which can be referenced in the API endpoints.
- bytes: Integer
  
  The size of the file, in bytes.
- created_at: Integer
  
  The Unix timestamp (in seconds) for when the file was created.
- filename: String
  
  The name of the file.
- object: :file
  
  The object type, which is always file.
  - :file
- purpose: :assistants | :assistants_output | :batch | 5 more
  
  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_output
  - :batch
  - :batch_output
  - :"fine-tune"
  - :"fine-tune-results"
  - :vision
  - :user_data
- status: :uploaded | :processed | :error
  
  Deprecated. The current status of the file, which can be either uploaded, processed, or error.
  - :uploaded
  - :processed
  - :error
- expires_at: Integer
  
  The Unix timestamp (in seconds) for when the file will expire.
- status_details: String
  
  Deprecated. For details on why a fine-tuning training file failed validation, see the error field on fine_tuning.job.

File Purpose

FilePurpose = :assistants | :batch | :"fine-tune" | 3 more

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
- :batch
- :"fine-tune"
- :vision
- :user_data
- :evals

ruby/resources/files/index.md +74 −8

6 6

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

8 8

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

10 10

11### Parameters11### Parameters

12 12

138 138

139**post** `/files`139**post** `/files`

140 140

141Upload file141Upload a file that can be used across various endpoints. Individual files

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

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

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

145user.

146

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

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

149 details.

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

151 certain required formats for fine-tuning

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

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

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

155 also has a specific required

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

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

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

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

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

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

162 organization.

163

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

165storage limits.

142 166

143### Parameters167### Parameters

144 168

146 170

147 The File object (not file name) to be uploaded.171 The File object (not file name) to be uploaded.

148 172

149- `purpose: untyped`173- `purpose: FilePurpose`

174

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

176

177 - `assistants`: Used in the Assistants API

178 - `batch`: Used in the Batch API

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

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

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

182 - `evals`: Used for eval data sets

183

184 - `:assistants`

185

186 - `:batch`

187

188 - `:"fine-tune"`

189

190 - `:vision`

191

192 - `:user_data`

193

194 - `:evals`

150 195

151- `expires_after: ExpiresAfter{ anchor, seconds}`196- `expires_after: ExpiresAfter{ anchor, seconds}`

152 197

235 280

236openai = OpenAI::Client.new(api_key: "My API Key")281openai = OpenAI::Client.new(api_key: "My API Key")

237 282

238file_object = openai.files.create(file: StringIO.new("Example data"), purpose: {})283file_object = openai.files.create(file: StringIO.new("Example data"), purpose: :assistants)

239 284

240puts(file_object)285puts(file_object)

241```286```

262 307

263**delete** `/files/{file_id}`308**delete** `/files/{file_id}`

264 309

265Delete file310Delete a file and remove it from all vector stores.

266 311

267### Parameters312### Parameters

268 313

308 353

309**get** `/files/{file_id}`354**get** `/files/{file_id}`

310 355

311Retrieve file356Returns information about a specific file.

312 357

313### Parameters358### Parameters

314 359

414 459

415**get** `/files/{file_id}/content`460**get** `/files/{file_id}/content`

416 461

417Retrieve file content462Returns the contents of the specified file.

418 463

419### Parameters464### Parameters

420 465

522 567

523### File Purpose568### File Purpose

524 569

525- `FilePurpose = untyped`570- `FilePurpose = :assistants | :batch | :"fine-tune" | 3 more`

571

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

573

574 - `assistants`: Used in the Assistants API

575 - `batch`: Used in the Batch API

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

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

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

579 - `evals`: Used for eval data sets

580

581 - `:assistants`

582

583 - `:batch`

584

585 - `:"fine-tune"`

586

587 - `:vision`

588

589 - `:user_data`

590

591 - `:evals`

ruby/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

Returns

Example

Domain Types

File Content

File Deleted

File Object

File Purpose