Files API

2026-10-22

Files API

File stores uploads for conversations and knowledge bases, with metadata, downloads and deletion. Concepts and behavior follow OpenAI Files (multipart uploads, purposes and file IDs), so OpenAI Files experience applies. Differences: uploads are limited to 104857600 bytes; only user_data, assistants and vision purposes are accepted, and conversation images require user_data; praxis[expires_in_seconds] allows expiry up to 90 days, while expires_after allows up to 30 days. Start with praxis.file.files.create to upload bytes and obtain a reusable file ID.

Base URL

Loading…

Get started

Loading…

The per-file limit is 100 MB (104857600 bytes). Uploads and downloads stream throughout; Uploads chunking is not available. Types are detected from content; see the upload endpoint for formats. Files are isolated by organization.

Endpoints

MethodPathDescriptionSupport
POST/v1/filesUpload a file◐ Partial
GET/v1/filesList files● Supported
GET/v1/files/{file_id}Retrieve a file● Supported
GET/v1/files/{file_id}/contentDownload a file● Supported
DELETE/v1/files/{file_id}Delete a file● Supported

Differences from OpenAI

  • Uses OpenAI file and pagination shapes, adding mime_type, downloadable and a before query cursor. Only this face accepts body praxis.expires_in_seconds (3600–7776000 seconds), mutually exclusive with expires_after; encode it as praxis[expires_in_seconds] in multipart.
  • Upload a file：Supports PDF; DOCX / XLSX / PPTX; PNG / JPEG / GIF / WebP; MP3 / WAV / FLAC / OGG / M4A; MP4 / WebM; UTF-8 JSON / NDJSON / CSV / Markdown / plain text. Purposes are user_data / assistants / vision. Limit 104857600 bytes. Empty, unsupported, invalid-purpose and oversized uploads return 400. No Uploads chunking. Set expiry with expires_after[anchor] and expires_after[seconds], or with praxis[expires_in_seconds]; the two settings are mutually exclusive.

For authoritative parameter definitions, see the official OpenAI documentation.

Errors follow the OpenAI format, see errors; quotas and response headers are covered in rate limits.

POST /file/v1/files◐ Partial

Official OpenAI docs ↗

Request body

  • filestring必填

    File bytes in one multipart file part, not a filename or file ID. The file must be nonempty and at most 104857600 bytes; its content determines the MIME type.

  • purposestring必填

    Purpose label stored with the file: user_data, assistants or vision. The vision purpose accepts only PNG, JPEG, GIF and WebP images. Conversation image references require user_data.

    取值 user_dataassistantsvision
  • expires_afterobject可选

    Optional expiry relative to created_at. Files without an expiry persist until deleted.

    ▸ 展开子字段（2）
    • anchorstring必填

      Creation timestamp from which expiry is measured. Send created_at as the multipart field expires_after[anchor].

      取值 created_at
    • secondsinteger必填

      Lifetime in seconds after creation, from 3600 through 2592000. Send as expires_after[seconds]; do not combine with praxis[expires_in_seconds].

  • praxisobject可选

    Own-face extensions. Use at most one expiry setting.

    ▸ 展开子字段（1）
    • expires_in_secondsinteger可选

      Lifetime in seconds after creation, from 3600 through 7776000. Send as the multipart field praxis[expires_in_seconds]; mutually exclusive with expires_after.

Returns

200 file

Supports PDF; DOCX / XLSX / PPTX; PNG / JPEG / GIF / WebP; MP3 / WAV / FLAC / OGG / M4A; MP4 / WebM; UTF-8 JSON / NDJSON / CSV / Markdown / plain text. Purposes are user_data / assistants / vision. Limit 104857600 bytes. Empty, unsupported, invalid-purpose and oversized uploads return 400. No Uploads chunking. Set expiry with expires_after[anchor] and expires_after[seconds], or with praxis[expires_in_seconds]; the two settings are mutually exclusive.

Errors follow the OpenAI format — see error codes

Response

HTTP 200

OK

application/json

NameTypeDescription
idstringFile identifier: file_dp_ followed by a 26-character uppercase Crockford ULID. Use the ID returned by upload or list.
bytesintegerThe size of the file, in bytes.
created_atintegerThe Unix timestamp (in seconds) for when the file was created.
expires_atintegerThe Unix timestamp (in seconds) for when the file will expire.
filenamestringThe name of the file.
objectstringThe object type, which is always `file`.
purposestringUpload purpose. Image references in conversations require user_data.
statusstringDeprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.
status_detailsstring | nullDeprecated; always null or absent.
mime_typestringContent-detected MIME type.
downloadablebooleanTenant-owned live files can be downloaded through this face.
scopeobjectPresent for session output files.
scope.typestringKind of scope; always `session`.
scope.idstringId of the session the file belongs to.
relative_pathstringPath within the session output directory; present for session outputs.
revisionintegerSession output revision; present for session outputs.

List files

GET /file/v1/files● Supported

Request parameters

  • purposestring可选

    query: Only return files with the given purpose.

  • limitinteger可选
    默认 10000

    query: A limit on the number of objects to be returned. Limit can range between 1 and 10,000, and the default is 10,000.

  • orderstring可选
    默认 "desc"

    query: Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.

    取值 ascdesc
  • afterstring可选

    query: File ID cursor for the next page; mutually exclusive with before. Use an ID from the current listing.

  • scope_idstring可选

    query: Session whose output files to list. Accepts sesn_ or ags_ followed by 1 to 251 letters, digits, underscores or hyphens. An existing session with no outputs returns an empty list; a nonexistent or inaccessible session returns 404.

  • beforestring可选

    query: File ID cursor for the preceding page; mutually exclusive with after. Use an ID from the current listing.

Returns

200 list

Errors follow the OpenAI format — see error codes

Response

HTTP 200

OK

application/json

NameTypeDescription
objectstringObject type; always `list`.
dataarray<object>Files of the page, in the requested order.
data[].idstringFile identifier: file_dp_ followed by a 26-character uppercase Crockford ULID. Use the ID returned by upload or list.
data[].bytesintegerThe size of the file, in bytes.
data[].created_atintegerThe Unix timestamp (in seconds) for when the file was created.
data[].expires_atintegerThe Unix timestamp (in seconds) for when the file will expire.
data[].filenamestringThe name of the file.
data[].objectstringThe object type, which is always `file`.
data[].purposestringUpload purpose. Image references in conversations require user_data.
data[].statusstringDeprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.
data[].status_detailsstring | nullDeprecated; always null or absent.
data[].mime_typestringContent-detected MIME type.
data[].downloadablebooleanTenant-owned live files can be downloaded through this face.
data[].scopeobjectPresent for session output files.
data[].relative_pathstringPath within the session output directory; present for session outputs.
data[].revisionintegerSession output revision; present for session outputs.
first_idstringId of the first file of the page; usable as `before` to read the preceding page.
last_idstringId of the last file of the page; usable as `after` to read the next page.
has_morebooleanWhether more files exist beyond this page.

Retrieve a file

Upload a file first, then replace the example file ID with its returned ID.

GET /file/v1/files/{file_id}● Supported

Request parameters

  • file_idstring必填

    path: ID of a tenant-owned live file, as returned by upload or list; starts with file_dp_.

Returns

200 file

Errors follow the OpenAI format — see error codes

Response

HTTP 200

OK

application/json

NameTypeDescription
idstringFile identifier: file_dp_ followed by a 26-character uppercase Crockford ULID. Use the ID returned by upload or list.
bytesintegerThe size of the file, in bytes.
created_atintegerThe Unix timestamp (in seconds) for when the file was created.
expires_atintegerThe Unix timestamp (in seconds) for when the file will expire.
filenamestringThe name of the file.
objectstringThe object type, which is always `file`.
purposestringUpload purpose. Image references in conversations require user_data.
statusstringDeprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.
status_detailsstring | nullDeprecated; always null or absent.
mime_typestringContent-detected MIME type.
downloadablebooleanTenant-owned live files can be downloaded through this face.
scopeobjectPresent for session output files.
scope.typestringKind of scope; always `session`.
scope.idstringId of the session the file belongs to.
relative_pathstringPath within the session output directory; present for session outputs.
revisionintegerSession output revision; present for session outputs.

Download a file

Upload a file first, then replace the example file ID with its returned ID.

GET /file/v1/files/{file_id}/content● Supported

Request parameters

  • file_idstring必填

    path: ID of a tenant-owned live file, as returned by upload or list; starts with file_dp_.

Returns

200

Errors follow the OpenAI format — see error codes

Response

HTTP 200

OK

application/octet-stream

NameTypeDescription
$string (binary)

Delete a file

Upload a file first, then replace the example file ID with its returned ID.

DELETE /file/v1/files/{file_id}● Supported

Request parameters

  • file_idstring必填

    path: ID of a tenant-owned live file, as returned by upload or list; starts with file_dp_.

Returns

200 file

Errors follow the OpenAI format — see error codes

Response

HTTP 200

OK

application/json

NameTypeDescription
idstringFile identifier: file_dp_ followed by a 26-character uppercase Crockford ULID. Use the ID returned by upload or list.
objectstringObject type; always `file`.
deletedbooleanAlways true; the file can no longer be read, though downloads already authorized may finish.