Files

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

string

required

The provider to route the request to (e.g. openai, azure-openai).

string

required

Your Portkey API key or the provider API key depending on your setup.

file

required

The file object to upload. Must be a supported file format for the target provider.

string

required

The intended purpose of the file. Common values: fine-tune, batch, assistants.

Response

string

The unique identifier for the uploaded file.

string

Always file.

number

Size of the file in bytes.

number

Unix timestamp when the file was created.

string

The name of the uploaded file.

string

The purpose the file was uploaded for.

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"

from openai import OpenAI

client = OpenAI(
    base_url="https://your-gateway.example.com/v1",
    api_key="YOUR_API_KEY",
    default_headers={
        "x-portkey-provider": "openai",
    },
)

with open("training_data.jsonl", "rb") as f:
    response = client.files.create(
        file=f,
        purpose="fine-tune",
    )

print(response.id)

import OpenAI, { toFile } from "openai";
import { createReadStream } from "fs";

const client = new OpenAI({
  baseURL: "https://your-gateway.example.com/v1",
  apiKey: "YOUR_API_KEY",
  defaultHeaders: {
    "x-portkey-provider": "openai",
  },
});

const response = await client.files.create({
  file: await toFile(createReadStream("training_data.jsonl"), "training_data.jsonl"),
  purpose: "fine-tune",
});

console.log(response.id);

List files

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

Request

string

required

The provider to route the request to.

string

required

Your Portkey API key or provider API key.

string

Filter files by purpose. For example, fine-tune or batch.

Response

string

Always list.

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"

files = client.files.list()
for file in files.data:
    print(file.id, file.filename, file.purpose)

const files = await client.files.list();
for (const file of files.data) {
  console.log(file.id, file.filename, file.purpose);
}

Retrieve file metadata

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

Request

string

required

The ID of the file to retrieve.

string

required

The provider to route the request to.

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"

file = client.files.retrieve("file-abc123")
print(file.id, file.status)

const file = await client.files.retrieve("file-abc123");
console.log(file.id, file.status);

Retrieve file content

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

Request

string

required

The ID of the file whose content to retrieve.

string

required

The provider to route the request to.

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

content = client.files.content("file-abc123")
with open("output.jsonl", "wb") as f:
    f.write(content.read())

const content = await client.files.content("file-abc123");
const buffer = await content.arrayBuffer();

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

string

required

The ID of the file to delete.

string

required

The provider to route the request to.

string

required

Your Portkey API key or provider API key.

Response

string

The ID of the deleted file.

string

Always file.

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"

result = client.files.delete("file-abc123")
print(result.deleted)

const result = await client.files.delete("file-abc123");
console.log(result.deleted);

Overview

Chat

Multimodal

Files & Batches

Other

Upload a file

Request

Response

List files

Request

Response

Retrieve file metadata

Request

Response

Retrieve file content

Request

Response

Delete a file

Request

Response

​Upload a file

​Request

​Response

​List files

​Request

​Response

​Retrieve file metadata

​Request

​Response

​Retrieve file content

​Request

​Response

​Delete a file

​Request

​Response

Upload a file

Request

Response

List files

Request

Response

Retrieve file metadata

Request

Response

Retrieve file content

Request

Response

Delete a file

Request

Response