File API Reference

The File API allows you to upload, list, retrieve, and manage files used by the Compass platform. These files can be used for batch processing, fine-tuning language models, vision features, and assistants.

Authentication

All API requests require a valid API key.

File Purposes

The File API supports the following purpose:

Purpose	Description	Format Requirements
`fine-tune`	For fine-tuning language models	JSONL format

File Format Requirements

All files are limited in size depending on the environment setup.

Fine-tuning Files

Must have .jsonl extension
Each line must be a valid JSON object
Format follows OpenAI's fine-tuning format

Upload a File

POST /files

Upload a file to utilize various features.

Request Parameters

Parameter	Type	Required	Description
file	file	Yes	The file to upload
purpose	string	Yes	Purpose of the file (batch, `fine-tune`, `vision`, or `assistants`)

Example Request

curl -X POST /v1/files \   
  -H "api-key: $API_KEY" \   
  -F "purpose=fine-tune" \   
  -F "file=@training_data.jsonl"

Example Response

{  
  "id": "file-abc123",
  "object": "file",
  "bytes": 120000,  
  "created_at": 1677610602,
  "expires_at": 1677614202,
  "filename": "training_data.jsonl",
  "purpose": "fine-tune",
}

List Files

GET /files

List files belonging to the user.

Query Parameters

Parameter	Required	Type	Description
purpose	No	string	Filter files by purpose.
limit	No	integer	Number of files to return. The default value is 10000.
after	No	string	Pagination cursor. The default value is null.
order	No	string	Sort order (`asc` or `desc`). The default value is `desc`.
filename	No	string	Filter by filename. The default value is null.

Example Request

curl /v1/files?purpose=fine-tune \   
-H "api-key: $API_KEY"

Example Response

{ 
   "object": "list",
   "data": [ 
     { 
        "id": "file-abc123",
        "object": "file",
        "bytes": 175,
        "created_at": 1613677385,
        "expires_at": 1677614202,
        "filename": "salesOverview.pdf",
        "purpose": "fine-tune",
     }, 
     { 
       "id": "file-abc456",
       "object": "file",
       "bytes": 140, 
       "created_at": 1613779121,
       "expires_at": 1677614202,
       "filename": "puppy.jsonl",
       "purpose": "fine-tune",
     } 
   ], 
   "first_id": "file-abc123",
   "last_id": "file-abc456",
   "has_more": false
}

Retrieve File

GET /files/{file_id}

Get information about a specific file.

Path Parameters

Parameter	Required	Type	Description
file_id	Yes	string	The ID of the file to retrieve

Example Request

curl /v1/files/file-abc123 \
  -H "api-key: $API_KEY"

Example Response

{
  "id": "file-abc123",
  "object": "file",
  "bytes": 120000,
  "created_at": 1677610602,
  "expires_at": 1677614202,
  "filename": "mydata.jsonl",
  "purpose": "fine-tune",
}

Delete File

DELETE /files/{file_id}

Deletes a file.

Request Parameters

Parameter	Required	Type	Description
file_id	Yes	string	The ID of the file to retrieve

Example Request

 curl /v1/files/file-abc123 \
  -X DELETE \
  -H "api-key: $API_KEY"

Example Response

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

Import File from URL

POST /files/import

Imports a file from a URL.

Request Parameters

Parameter	Required	Type	Description
content_url	Yes	string	The URL from which to import the file
purpose	Yes	string	Purpose of the file (`fine-tune`, `vision`, or `assistants`)
filename	Yes	string	Name to give the imported file

Example Request

curl /v1/file/import' \
--header 'api-key: $API_KEY' \
--data '{
    "content_url":"https://raw.githubusercontent.com/openai/openai-cookbook/refs/heads/main/examples/data/toy_chat_fine_tuning.jsonl",
    "filename": "sample.jsonl",
    "purpose": "fine-tune"
}'

Example Response

{
    "id": "file-8e25a26c056b4c749a5189f3abc07217",
    "bytes": 474,
    "created_at": 1755190481,
    "filename": "sample.jsonl",
    "object": "file",
    "purpose": "fine-tune",
    "expires_at": 1762966481
}

Retrieve File Content

GET /files/{file_id}/content

Download the content of a file.

Path Parameters

Parameter	Required	Type	Description
file_id	Yes	string	The ID of the file to download

Example Request

curl https://api.openai.com/v1/files/file-abc123/content \
  -H "api-key: $API_KEY"

Response

Returns the raw file content as a download.