Skip to main content
POST
cURL
The files endpoints store documents for reuse across chat requests. Files are scoped to the workspace that uploaded them; another workspace’s file id returns 404.

Upload

The upload takes the bytes in a file part and a purpose string (user_data for documents you will reference from chat messages) and returns the stored file object, including the id used in later requests.

List, fetch, download, delete

The list has only files this workspace uploaded through the gateway, newest first (order=asc for oldest first), 20 per page by default and at most 50 (limit). To page, pass last_id as after while has_more is true; after must be one of this workspace’s files, otherwise the call returns 404. purpose lists only files with that purpose. A page can hold fewer than limit files: a file whose read fails or takes more than 5 seconds is skipped, and a call that reaches 10 seconds leaves the rest for the next page. Skipped ids are in predev.skipped, which appears only when something was skipped; GET /v1/files/{id} fetches them. Only files whose metadata says downloadable: true can be downloaded; a file you uploaded returns 400 from /content. In the SDKs these are client.files.list(), client.files.retrieve(id), client.files.content(id), and client.files.delete(id) (Node client.files.del(id) on older versions).

Use a file in a request

Reference the uploaded file from a chat message as a file content part, and add the file-parser plugin so models without native document input can read it. See multimodal.

Authorizations

Authorization
string
header
required

The workspace API key (pdk_…) from Integrations → Built-in in the pre.dev dashboard.

Body

multipart/form-data
file
file
required

Up to 60 MB. PDF, PNG, JPEG, GIF, WebP, DOCX, XLSX, PPTX, MP3, WAV, FLAC, OGG, or UTF-8 text. The type is read from the contents.

purpose
string

Sent by the OpenAI SDKs, for example user_data.

Example:

"user_data"

Response

The stored file.

File metadata. id and filename are always present. The other fields follow one of two styles: object: "file", bytes, purpose and a Unix created_at, or type: "file", size_bytes, mime_type, downloadable and an ISO created_at.

id
string
required

Use it in a file content part as file_id.

filename
string
required
object
string
Allowed value: "file"
type
string
Allowed value: "file"
bytes
integer
size_bytes
integer
mime_type
string
purpose
string
created_at
downloadable
boolean

Whether GET /v1/files/{id}/content can return the bytes.