Files

Upload files for use with Batches or as searchable knowledge documents.

Per-file cap: 100 MB. Per-user storage quota: 1 GB. Files auto-expire 30 days post-upload.

Endpoints

Method Path Purpose
POST /v1/files Multipart upload
GET /v1/files List your files (optional ?purpose= filter)
GET /v1/files/{file_id} File metadata
GET /v1/files/{file_id}/content Download raw content
DELETE /v1/files/{file_id} Soft-delete + storage purge

Supported purpose values

Purpose Used by Accepted formats
batch_input /v1/batches as input file JSONL (one request per line)
knowledge /v1/retrieval via async ingest worker PDF, TXT, MD

Batch output and error files (returned from completed batches) appear with purposes batch_output and batch_error. You can list / download / delete them, but they cannot be uploaded directly.

Upload

r = client.files.create(
    file=open("batch_requests.jsonl", "rb"),
    purpose="batch_input",
)
print(r.id)         # file-abc123...
print(r.status)     # "uploaded" - immediately ready for /v1/batches
print(r.expires_at) # unix ts, default upload + 30 days

For knowledge documents:

r = client.files.create(
    file=open("hotel_handbook.pdf", "rb"),
    purpose="knowledge",
)
# Background processor extracts text -> chunks -> embeds asynchronously.
# Poll r.status: "uploaded" -> "processed" (typically <30s for typical docs).

File object shape

{
  "id": "file-abc123...",
  "object": "file",
  "bytes": 1278,
  "created_at": 1778765001,
  "filename": "batch_requests.jsonl",
  "purpose": "batch_input",
  "status": "uploaded",
  "expires_at": 1781357001
}

Status values:

List

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

Filter by purpose:

r = httpx.get(
    "https://api.epithre.com/v1/files?purpose=knowledge",
    headers={"Authorization": f"Bearer {EPITHRE_KEY}"},
).json()

Download content

out = client.files.content(file_id="file-abc123...")
content_bytes = out.read()

Delete

client.files.delete(file_id="file-abc123...")
# Soft-deletes (status="deleted") + purges from disk.

Limits

When you hit the quota, uploads return 413. Delete old files first.

See also