Skip to main content
The Files API proxies file management requests to the configured provider. All endpoints follow the OpenAI Files API contract and are forwarded via the Portkey gateway using your provider credentials.
You must include your provider credentials via the x-portkey-api-key header or a virtual key. See Authentication for details.

​
Upload a file

POST /v1/files Uploads a file that can be used with fine-tuning, batch processing, or other provider features. The request body must be multipart/form-data.

​
Request

​
x-portkey-provider
string
required
The provider to route the request to (e.g. openai, azure-openai).
​
x-portkey-api-key
string
required
Your Portkey API key or the provider API key depending on your setup.
​
file
file
required
The file object to upload. Must be a supported file format for the target provider.
​
purpose
string
required
The intended purpose of the file. Common values: fine-tune, batch, assistants.

​
Response

​
id
string
The unique identifier for the uploaded file.
​
object
string
Always file.
​
bytes
number
Size of the file in bytes.
​
created_at
number
Unix timestamp when the file was created.
​
filename
string
The name of the uploaded file.
​
purpose
string
The purpose the file was uploaded for.
​
status
string
Processing status of the file. Values: uploaded, processed, error.
curl https://your-gateway.example.com/v1/files \
  -X POST \
  -H "x-portkey-api-key: YOUR_API_KEY" \
  -H "x-portkey-provider: openai" \
  -F "purpose=fine-tune" \
  -F "file=@training_data.jsonl"

​
List files

GET /v1/files Returns a list of files that have been uploaded to the configured provider.

​
Request

​
x-portkey-provider
string
required
The provider to route the request to.
​
x-portkey-api-key
string
required
Your Portkey API key or provider API key.
​
purpose
string
Filter files by purpose. For example, fine-tune or batch.

​
Response

​
object
string
Always list.
​
data
array
Array of file objects. Each object has the same shape as the Upload a file response.
curl https://your-gateway.example.com/v1/files \
  -H "x-portkey-api-key: YOUR_API_KEY" \
  -H "x-portkey-provider: openai"

​
Retrieve file metadata

GET /v1/files/:id Returns metadata for a specific file by its ID.

​
Request

​
id
string
required
The ID of the file to retrieve.
​
x-portkey-provider
string
required
The provider to route the request to.
​
x-portkey-api-key
string
required
Your Portkey API key or provider API key.

​
Response

Returns a single file object with the same fields as the Upload a file response. 
curl https://your-gateway.example.com/v1/files/file-abc123 \
  -H "x-portkey-api-key: YOUR_API_KEY" \
  -H "x-portkey-provider: openai"

​
Retrieve file content

GET /v1/files/:id/content Returns the raw content of a file.

​
Request

​
id
string
required
The ID of the file whose content to retrieve.
​
x-portkey-provider
string
required
The provider to route the request to.
​
x-portkey-api-key
string
required
Your Portkey API key or provider API key.

​
Response

Returns the raw file bytes with the content type set by the provider. 
curl https://your-gateway.example.com/v1/files/file-abc123/content \
  -H "x-portkey-api-key: YOUR_API_KEY" \
  -H "x-portkey-provider: openai" \
  --output file_content.jsonl

​
Delete a file

DELETE /v1/files/:id Deletes a file from the provider. The file must not be in use by any active fine-tuning jobs or batches.
Deletion is permanent. Ensure the file is no longer referenced by any active jobs before deleting it.

​
Request

​
id
string
required
The ID of the file to delete.
​
x-portkey-provider
string
required
The provider to route the request to.
​
x-portkey-api-key
string
required
Your Portkey API key or provider API key.

​
Response

​
id
string
The ID of the deleted file.
​
object
string
Always file.
​
deleted
boolean
true if the file was successfully deleted.
curl https://your-gateway.example.com/v1/files/file-abc123 \
  -X DELETE \
  -H "x-portkey-api-key: YOUR_API_KEY" \
  -H "x-portkey-provider: openai"

Build docs developers (and LLMs) love

Get started for freeTalk to us