OpenAI Files API
Files are used to upload documents that can be used with features like Assistants and Fine-tuning. Upload a file that can be used across various endpoints. The size of all the files uploaded by one organization can be up to 100 GB.
OpenAPI Specification
openapi: 3.0.0
info:
title: 'OpenAI files'
description: Needs description.
version: 2.0.0
termsOfService: https://openai.com/policies/terms-of-use
contact:
name: OpenAI Support
url: https://help.openai.com/
license:
name: MIT
url: https://github.com/openai/openai-openapi/blob/master/LICENSE
servers:
- url: https://api.openai.com/v1
tags:
- name: Assistants
description: Build Assistants that can call models and use tools.
- name: Files
description: >-
Files are used to upload documents that can be used with features like
Assistants and Fine-tuning.
- name: Threads
paths:
/files:
get:
operationId: listFiles
tags:
- Files
summary: OpenAI Returns a list of files that belong to the user's organization.
parameters:
- in: query
name: purpose
required: false
schema:
type: string
description: Only return files with the given purpose.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListFilesResponse'
x-oaiMeta:
name: List files
group: files
returns: A list of [File](/docs/api-reference/files/object) objects.
examples:
request:
curl: |
curl https://api.openai.com/v1/files \
-H "Authorization: Bearer $OPENAI_API_KEY"
python: |
from openai import OpenAI
client = OpenAI()
client.files.list()
node.js: |-
import OpenAI from "openai";
const openai = new OpenAI();
async function main() {
const list = await openai.files.list();
for await (const file of list) {
console.log(file);
}
}
main();
response: |
{
"data": [
{
"id": "file-abc123",
"object": "file",
"bytes": 175,
"created_at": 1613677385,
"filename": "salesOverview.pdf",
"purpose": "assistants",
},
{
"id": "file-abc123",
"object": "file",
"bytes": 140,
"created_at": 1613779121,
"filename": "puppy.jsonl",
"purpose": "fine-tune",
}
],
"object": "list"
}
post:
operationId: createFile
tags:
- Files
summary: >
Upload a file that can be used across various endpoints. The size of all
the files uploaded by one organization can be up to 100 GB.
The size of individual files can be a maximum of 512 MB or 2 million
tokens for Assistants. See the [Assistants Tools
guide](/docs/assistants/tools) to learn more about the types of files
supported. The Fine-tuning API only supports `.jsonl` files.
Please [contact us](https://help.openai.com/) if you need to increase
these storage limits.
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/CreateFileRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIFile'
x-oaiMeta:
name: Upload file
group: files
returns: The uploaded [File](/docs/api-reference/files/object) object.
examples:
request:
curl: |
curl https://api.openai.com/v1/files \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-F purpose="fine-tune" \
-F file="@mydata.jsonl"
python: |
from openai import OpenAI
client = OpenAI()
client.files.create(
file=open("mydata.jsonl", "rb"),
purpose="fine-tune"
)
node.js: |-
import fs from "fs";
import OpenAI from "openai";
const openai = new OpenAI();
async function main() {
const file = await openai.files.create({
file: fs.createReadStream("mydata.jsonl"),
purpose: "fine-tune",
});
console.log(file);
}
main();
response: |
{
"id": "file-abc123",
"object": "file",
"bytes": 120000,
"created_at": 1677610602,
"filename": "mydata.jsonl",
"purpose": "fine-tune",
}
/files/{file_id}:
delete:
operationId: deleteFile
tags:
- Files
summary: OpenAI Delete a file.
parameters:
- in: path
name: file_id
required: true
schema:
type: string
description: The ID of the file to use for this request.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteFileResponse'
x-oaiMeta:
name: Delete file
group: files
returns: Deletion status.
examples:
request:
curl: |
curl https://api.openai.com/v1/files/file-abc123 \
-X DELETE \
-H "Authorization: Bearer $OPENAI_API_KEY"
python: |
from openai import OpenAI
client = OpenAI()
client.files.delete("file-abc123")
node.js: |-
import OpenAI from "openai";
const openai = new OpenAI();
async function main() {
const file = await openai.files.del("file-abc123");
console.log(file);
}
main();
response: |
{
"id": "file-abc123",
"object": "file",
"deleted": true
}
get:
operationId: retrieveFile
tags:
- Files
summary: OpenAI Returns information about a specific file.
parameters:
- in: path
name: file_id
required: true
schema:
type: string
description: The ID of the file to use for this request.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIFile'
x-oaiMeta:
name: Retrieve file
group: files
returns: >-
The [File](/docs/api-reference/files/object) object matching the
specified ID.
examples:
request:
curl: |
curl https://api.openai.com/v1/files/file-abc123 \
-H "Authorization: Bearer $OPENAI_API_KEY"
python: |
from openai import OpenAI
client = OpenAI()
client.files.retrieve("file-abc123")
node.js: |-
import OpenAI from "openai";
const openai = new OpenAI();
async function main() {
const file = await openai.files.retrieve("file-abc123");
console.log(file);
}
main();
response: |
{
"id": "file-abc123",
"object": "file",
"bytes": 120000,
"created_at": 1677610602,
"filename": "mydata.jsonl",
"purpose": "fine-tune",
}
/files/{file_id}/content:
get:
operationId: downloadFile
tags:
- Files
summary: OpenAI Returns the contents of the specified file.
parameters:
- in: path
name: file_id
required: true
schema:
type: string
description: The ID of the file to use for this request.
responses:
'200':
description: OK
content:
application/json:
schema:
type: string
x-oaiMeta:
name: Retrieve file content
group: files
returns: The file content.
examples:
request:
curl: |
curl https://api.openai.com/v1/files/file-abc123/content \
-H "Authorization: Bearer $OPENAI_API_KEY" > file.jsonl
python: |
from openai import OpenAI
client = OpenAI()
content = client.files.retrieve_content("file-abc123")
node.js: |
import OpenAI from "openai";
const openai = new OpenAI();
async function main() {
const file = await openai.files.retrieveContent("file-abc123");
console.log(file);
}
main();
/assistants/{assistant_id}/files:
get:
operationId: listAssistantFiles
tags:
- Assistants
summary: OpenAI Returns a list of assistant files.
parameters:
- name: assistant_id
in: path
description: The ID of the assistant the file belongs to.
required: true
schema:
type: string
- name: limit
in: query
description: >
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 20.
required: false
schema:
type: integer
default: 20
- name: order
in: query
description: >
Sort order by the `created_at` timestamp of the objects. `asc` for
ascending order and `desc` for descending order.
schema:
type: string
default: desc
enum:
- asc
- desc
- name: after
in: query
description: >
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.
schema:
type: string
- name: before
in: query
description: >
A cursor for use in pagination. `before` 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 before=obj_foo in order to fetch the
previous page of the list.
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListAssistantFilesResponse'
x-oaiMeta:
name: List assistant files
group: assistants
beta: true
returns: >-
A list of [assistant file](/docs/api-reference/assistants/file-object)
objects.
examples:
request:
curl: |
curl https://api.openai.com/v1/assistants/asst_abc123/files \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-H "OpenAI-Beta: assistants=v1"
python: |
from openai import OpenAI
client = OpenAI()
assistant_files = client.beta.assistants.files.list(
assistant_id="asst_abc123"
)
print(assistant_files)
node.js: |
import OpenAI from "openai";
const openai = new OpenAI();
async function main() {
const assistantFiles = await openai.beta.assistants.files.list(
"asst_abc123"
);
console.log(assistantFiles);
}
main();
response: |
{
"object": "list",
"data": [
{
"id": "file-abc123",
"object": "assistant.file",
"created_at": 1699060412,
"assistant_id": "asst_abc123"
},
{
"id": "file-abc456",
"object": "assistant.file",
"created_at": 1699060412,
"assistant_id": "asst_abc123"
}
],
"first_id": "file-abc123",
"last_id": "file-abc456",
"has_more": false
}
post:
operationId: createAssistantFile
tags:
- Assistants
summary: >-
OpenAI Create an assistant file by attaching a [File](/docs/api-reference/files) to an [assistant](/docs/api-reference/assistants).
parameters:
- in: path
name: assistant_id
required: true
schema:
type: string
example: file-abc123
description: |
The ID of the assistant for which to create a File.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAssistantFileRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AssistantFileObject'
x-oaiMeta:
name: Create assistant file
group: assistants
beta: true
returns: >-
An [assistant file](/docs/api-reference/assistants/file-object)
object.
examples:
request:
curl: |
curl https://api.openai.com/v1/assistants/asst_abc123/files \
-H 'Authorization: Bearer $OPENAI_API_KEY"' \
-H 'Content-Type: application/json' \
-H 'OpenAI-Beta: assistants=v1' \
-d '{
"file_id": "file-abc123"
}'
python: |
from openai import OpenAI
client = OpenAI()
assistant_file = client.beta.assistants.files.create(
assistant_id="asst_abc123",
file_id="file-abc123"
)
print(assistant_file)
node.js: |
import OpenAI from "openai";
const openai = new OpenAI();
async function main() {
const myAssistantFile = await openai.beta.assistants.files.create(
"asst_abc123",
{
file_id: "file-abc123"
}
);
console.log(myAssistantFile);
}
main();
response: |
{
"id": "file-abc123",
"object": "assistant.file",
"created_at": 1699055364,
"assistant_id": "asst_abc123"
}
/assistants/{assistant_id}/files/{file_id}:
get:
operationId: getAssistantFile
tags:
- Assistants
summary: OpenAI Retrieves an AssistantFile.
parameters:
- in: path
name: assistant_id
required: true
schema:
type: string
description: The ID of the assistant who the file belongs to.
- in: path
name: file_id
required: true
schema:
type: string
description: The ID of the file we're getting.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AssistantFileObject'
x-oaiMeta:
name: Retrieve assistant file
group: assistants
beta: true
returns: >-
The [assistant file](/docs/api-reference/assistants/file-object)
object matching the specified ID.
examples:
request:
curl: >
curl
https://api.openai.com/v1/assistants/asst_abc123/files/file-abc123
\
-H 'Authorization: Bearer $OPENAI_API_KEY"' \
-H 'Content-Type: application/json' \
-H 'OpenAI-Beta: assistants=v1'
python: |
from openai import OpenAI
client = OpenAI()
assistant_file = client.beta.assistants.files.retrieve(
assistant_id="asst_abc123",
file_id="file-abc123"
)
print(assistant_file)
node.js: |
import OpenAI from "openai";
const openai = new OpenAI();
async function main() {
const myAssistantFile = await openai.beta.assistants.files.retrieve(
"asst_abc123",
"file-abc123"
);
console.log(myAssistantFile);
}
main();
response: |
{
"id": "file-abc123",
"object": "assistant.file",
"created_at": 1699055364,
"assistant_id": "asst_abc123"
}
delete:
operationId: deleteAssistantFile
tags:
- Assistants
summary: OpenAI Delete an assistant file.
parameters:
- in: path
name: assistant_id
required: true
schema:
type: string
description: The ID of the assistant that the file belongs to.
- in: path
name: file_id
required: true
schema:
type: string
description: The ID of the file to delete.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteAssistantFileResponse'
x-oaiMeta:
name: Delete assistant file
group: assistants
beta: true
returns: Deletion status
examples:
request:
curl: >
curl
https://api.openai.com/v1/assistants/asst_abc123/files/file-abc123
\
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-H "OpenAI-Beta: assistants=v1" \
-X DELETE
python: |
from openai import OpenAI
client = OpenAI()
deleted_assistant_file = client.beta.assistants.files.delete(
assistant_id="asst_abc123",
file_id="file-abc123"
)
print(deleted_assistant_file)
node.js: |
import OpenAI from "openai";
const openai = new OpenAI();
async function main() {
const deletedAssistantFile = await openai.beta.assistants.files.del(
"asst_abc123",
"file-abc123"
);
console.log(deletedAssistantFile);
}
main();
response: |
{
id: "file-abc123",
object: "assistant.file.deleted",
deleted: true
}
/threads/{thread_id}/messages/{message_id}/files:
get:
operationId: listMessageFiles
tags:
- Threads
summary: OpenAI Returns a list of message files.
parameters:
- name: thread_id
in: path
description: The ID of the thread that the message and files belong to.
required: true
schema:
type: string
- name: message_id
in: path
description: The ID of the message that the files belongs to.
required: true
schema:
type: string
- name: limit
in: query
description: >
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 20.
required: false
schema:
type: integer
default: 20
- name: order
in: query
description: >
Sort order by the `created_at` timestamp of the objects. `asc` for
ascending order and `desc` for descending order.
schema:
type: string
default: desc
enum:
- asc
- desc
- name: after
in: query
description: >
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.
schema:
type: string
- name: before
in: query
description: >
A cursor for use in pagination. `before` 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 before=obj_foo in order to fetch the
previous page of the list.
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListMessageFilesResponse'
x-oaiMeta:
name: List message files
group: threads
beta: true
returns: >-
A list of [message file](/docs/api-reference/messages/file-object)
objects.
examples:
request:
curl: >
curl
https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123/files
\
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-H "OpenAI-Beta: assistants=v1"
python: |
from openai import OpenAI
client = OpenAI()
message_files = client.beta.threads.messages.files.list(
thread_id="thread_abc123",
message_id="msg_abc123"
)
print(message_files)
node.js: |
import OpenAI from "openai";
const openai = new OpenAI();
async function main() {
const messageFiles = await openai.beta.threads.messages.files.list(
"thread_abc123",
"msg_abc123"
);
console.log(messageFiles);
}
main();
response: |
{
"object": "list",
"data": [
{
"id": "file-abc123",
"object": "thread.message.file",
"created_at": 1699061776,
"message_id": "msg_abc123"
},
{
"id": "file-abc123",
"object": "thread.message.file",
"created_at": 1699061776,
"message_id": "msg_abc123"
}
],
"first_id": "file-abc123",
"last_id": "file-abc123",
"has_more": false
}
/threads/{thread_id}/messages/{message_id}/files/{file_id}:
get:
operationId: getMessageFile
tags:
- Threads
summary: OpenAI Retrieves a message file.
parameters:
- in: path
name: thread_id
required: true
schema:
type: string
example: thread_abc123
description: The ID of the thread to which the message and File belong.
- in: path
name: message_id
required: true
schema:
type: string
example: msg_abc123
description: The ID of the message the file belongs to.
- in: path
name: file_id
required: true
schema:
type: string
example: file-abc123
description: The ID of the file being retrieved.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MessageFileObject'
x-oaiMeta:
name: Retrieve message file
group: threads
beta: true
returns: The [message file](/docs/api-reference/messages/file-object) object.
examples:
request:
curl: >
curl
https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123/files/file-abc123
\
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-H "OpenAI-Beta: assistants=v1"
python: |
from openai import OpenAI
client = OpenAI()
message_files = client.beta.threads.messages.files.retrieve(
thread_id="thread_abc123",
message_id="msg_abc123",
file_id="file-abc123"
)
print(message_files)
node.js: |
import OpenAI from "openai";
const openai = new OpenAI();
async function main() {
const messageFile = await openai.beta.threads.messages.files.retrieve(
"thread_abc123",
"msg_abc123",
"file-abc123"
);
console.log(messageFile);
}
main();
response: |
{
"id": "file-abc123",
"object": "thread.message.file",
"created_at": 1699061776,
"message_id": "msg_abc123"
}
components:
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
schemas:
ListFilesResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/OpenAIFile'
object:
type: string
enum:
- list
required:
- object
- data
OpenAIFile:
title: OpenAIFile
description: >-
The `File` object represents a document that has been uploaded to
OpenAI.
properties:
id:
type: string
description: The file identifier, which can be referenced in the API endpoints.
bytes:
type: integer
description: The size of the file, in bytes.
created_at:
type: integer
description: The Unix timestamp (in seconds) for when the file was created.
filename:
type: string
description: The name of the file.
object:
type: string
description: The object type, which is always `file`.
enum:
- file
purpose:
type: string
description: >-
The intended purpose of the file. Supported values are `fine-tune`,
`fine-tune-results`, `assistants`, and `assistants_output`.
enum:
- fine-tune
- fine-tune-results
- assistants
- assistants_output
status:
type: string
deprecated: true
description: >-
Deprecated. The current status of the file, which can be either
`uploaded`, `processed`, or `error`.
enum:
- uploaded
- processed
- error
status_details:
type: string
deprecated: true
description: >-
Deprecated. For details on why a fine-tuning training file failed
validation, see the `error` field on `fine_tuning.job`.
required:
- id
- object
- bytes
- created_at
- filename
- purpose
- status
x-oaiMeta:
name: The file object
example: |
{
"id": "file-abc123",
"object": "file",
"bytes": 120000,
"created_at": 1677610602,
"filename": "salesOverview.pdf",
"purpose": "assistants",
}
DeleteFileResponse:
type: object
properties:
id:
type: string
object:
type: string
enum:
- file
deleted:
type: boolean
required:
- id
- object
- deleted
ListAssistantFilesResponse:
properties:
object:
type: string
example: list
data:
type: array
items:
$ref: '#/components/schemas/AssistantFileObject'
first_id:
type: string
example: file-abc123
last_id:
type: string
example: file-abc456
has_more:
type: boolean
example: false
required:
- object
- data
- items
- first_id
- last_id
- has_more
AssistantFileObject:
type: object
title: Assistant files
description: A list of [Files](/docs/api-reference/files) attached to an `assistant`.
properties:
id:
description: The identifier, which can be referenced in API endpoints.
type: string
object:
description: The object type, which is always `assistant.file`.
type: string
enum:
- assistant.file
created_at:
description: >-
The Unix timestamp (in seconds) for when the assistant file was
created.
type: integer
assistant_id:
description: The assistant ID that the file is attached to.
type: string
required:
- id
- object
- created_at
- assistant_id
x-oaiMeta:
name: The assistant file object
beta: true
example: |
{
"id": "file-abc123",
"object": "assistant.file",
"created_at": 1699055364,
"assistant_id": "asst_abc123"
}
DeleteAssistantFileResponse:
type: object
description: >-
Deletes the association between the assistant and the file, but does not
delete the [File](/docs/api-reference/files) object itself.
properties:
id:
type: string
deleted:
type: boolean
object:
type: string
enum:
- assistant.file.deleted
required:
- id
- object
- deleted
ListMessageFilesResponse:
properties:
object:
type: string
example: list
data:
type: array
items:
$ref: '#/components/schemas/MessageFileObject'
first_id:
type: string
example: file-abc123
last_id:
type: string
example: file-abc456
has_more:
type: boolean
example: false
required:
- object
- data
- items
- first_id
- last_id
- has_more
MessageFileObject:
type: object
title: Message files
description: A list of files attached to a `message`.
properties:
id:
description: The identifier, which can be referenced in API endpoints.
type: string
object:
description: The object type, which is always `thread.message.file`.
type: string
enum:
- thread.message.file
created_at:
description: >-
The Unix timestamp (in seconds) for when the message file was
created.
type: integer
message_id:
description: >-
The ID of the [message](/docs/api-referen
# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/openai/refs/heads/main/openapi/files-openapi-original.yml