Files

Overview

The Files API stores blobs that are referenced by other endpoints. Common use cases:

• Fine-tuning -- upload JSONL training and validation datasets
• Batch processing -- upload a JSONL of inputs for asynchronous processing
• File parser plugin -- upload PDFs, DOCX, XLSX for context augmentation
• Image edits -- upload PNG sources and masks
• Audio -- upload large audio files for transcription

Files are stored in AllRoutes-managed encrypted object storage. Each file has a unique file_id that other endpoints reference.

Upload

POST https://api.allroutes.ai/v1/files

Multipart form upload.

Field	Type	Required	Description
file	file	Yes	The file to upload (max 512 MB)
purpose	string	Yes	fine-tune, batch, assistants, vision, user_data

Example

curl https://api.allroutes.ai/v1/files \
  -H "Authorization: Bearer allroutes_sk_..." \
  -F purpose=fine-tune \
  -F [email protected]

Response

{
  "id": "file_abc123",
  "object": "file",
  "bytes": 524288,
  "filename": "training.jsonl",
  "purpose": "fine-tune",
  "created_at": 1714000000,
  "status": "processed",
  "status_details": null
}

List

GET https://api.allroutes.ai/v1/files

Query Param	Type	Description
purpose	string	Filter by purpose
limit	integer	Max results (default: 100, max: 10000)
order	string	asc or desc (default: desc by created_at)
after	string	Cursor for pagination

curl "https://api.allroutes.ai/v1/files?purpose=fine-tune&limit=20" \
  -H "Authorization: Bearer allroutes_sk_..."

Retrieve Metadata

GET https://api.allroutes.ai/v1/files/:file_id

curl https://api.allroutes.ai/v1/files/file_abc123 \
  -H "Authorization: Bearer allroutes_sk_..."

Download Contents

GET https://api.allroutes.ai/v1/files/:file_id/content

Returns the raw file bytes. Set the appropriate Accept header if you need a specific content type.

curl https://api.allroutes.ai/v1/files/file_abc123/content \
  -H "Authorization: Bearer allroutes_sk_..." \
  --output training.jsonl

Delete

DELETE https://api.allroutes.ai/v1/files/:file_id

curl -X DELETE https://api.allroutes.ai/v1/files/file_abc123 \
  -H "Authorization: Bearer allroutes_sk_..."

Response

{
  "id": "file_abc123",
  "object": "file",
  "deleted": true
}

Purposes

Each purpose constrains how the file can be used and what validation runs at upload time:

Purpose	Accepted Formats	Max Size	Validation
fine-tune	JSONL (chat format)	512 MB	Schema-validated; line-by-line parsing
batch	JSONL	512 MB	Schema-validated against batch envelope
assistants	Most formats	512 MB	None
vision	PNG, JPEG, WEBP	20 MB	Image dimension check
user_data	Any	512 MB	None

SDK Examples

Python

# Upload
with open("training.jsonl", "rb") as f:
    upload = client.files.create(file=f, purpose="fine-tune")
print(upload.id)

# List
files = client.files.list(purpose="fine-tune")
for f in files.data:
    print(f"{f.id}: {f.filename} ({f.bytes} bytes)")

# Download
content = client.files.content("file_abc123")
with open("downloaded.jsonl", "wb") as out:
    out.write(content.read())

# Delete
client.files.delete("file_abc123")

Node.js

import fs from "fs";

const upload = await client.files.create({
  file: fs.createReadStream("training.jsonl"),
  purpose: "fine-tune",
});

const files = await client.files.list({ purpose: "fine-tune" });
for (const f of files.data) {
  console.log(`${f.id}: ${f.filename} (${f.bytes} bytes)`);
}

const content = await client.files.content("file_abc123");
fs.writeFileSync("downloaded.jsonl", Buffer.from(await content.arrayBuffer()));

await client.files.del("file_abc123");

Lifecycle and Quotas

• Per-organization quota -- 100 GB total file storage on Free, 1 TB on Pro, custom on Enterprise
• Auto-expiration -- files with purpose: vision expire after 24 hours; all other purposes are retained until you delete them
• Idempotency -- uploads are not deduplicated; the same file uploaded twice produces two file_ids

Storage usage is visible in the dashboard under Settings > Files along with per-purpose breakdowns.

Privacy and Encryption

• Files are encrypted at rest with AES-256-GCM
• Encryption keys are organization-scoped and rotated quarterly
• Pre-signed download URLs expire after 1 hour
• BYOK provider keys never see file blobs except when explicitly referenced (e.g., during fine-tuning the JSONL is sent to the provider)

For the strictest data-handling requirements, see Zero Data Retention in Guardrails.

Troubleshooting

Symptom	Cause	Fix
413 Payload Too Large	File over 512 MB	Split or compress
400: invalid_jsonl	One or more JSONL lines malformed	jq -c < file.jsonl to validate
quota_exceeded	Storage quota hit	Delete unused files or upgrade plan
Download returns empty body	File is still processing	Poll metadata until status: "processed"

See Also

• Fine-Tuning -- consumes JSONL files via training_file
• Plugins -- the file-parser plugin reads uploaded PDFs/DOCX
• Images API -- alternative path for image edit sources
• Audio API -- direct audio upload without Files API