Skip to main content

Stateful Tenant Files API

GoRoute AI Gateway implements OpenAI-compatible stateful file management to support asynchronous batch processing (/v1/batches), fine-tuning workflows, and multi-modal assistants. Files are isolated per organization, validated for integrity via streaming cryptographic hashes, and stored with strict POSIX permissions.


Endpoint Specification​

EndpointMethodOutputDescription
/v1/filesPOSTCanonicalFile JSONUpload a new tenant file (up to 512 MB).
/v1/filesGETList JSONList all active files for the authenticated organization.
/v1/files/{file_id}GETCanonicalFile JSONRetrieve metadata for a specific file.
/v1/files/{file_id}/contentGETBinary StreamDownload raw binary or text file contents.
/v1/files/{file_id}DELETEDeletion StatusPermanently delete file from database and disk storage.
  • Authentication: Bearer sk-gw-... (Virtual Key identity required)
  • Max Upload Limit: 512 MB per file (enforced via http.MaxBytesReader)
  • Per-Organization Storage Quota: 5 GiB default (server.max_file_storage_bytes_per_org / GATEWAY_MAX_FILE_STORAGE_BYTES_PER_ORG; returns HTTP 413 storage_quota_exceeded when exceeded)
  • Upload Concurrency Limit: 8 concurrent uploads default (server.max_concurrent_file_uploads / GATEWAY_MAX_CONCURRENT_FILE_UPLOADS; returns HTTP 429 upload_concurrency_limit when saturated)
  • Default Storage Path: Configured via GOROUTE_FILES_DIR or defaults to /tmp/goroute-files

Architecture: Multi-Tenant Storage & Streaming Hashes​

1. POST /v1/files (multipart/form-data) 2. Stream chunk to file descriptor 3. io.MultiWriter feeds SHA-256 4. Sync file to disk (0700 dir) 5. INSERT INTO files (id, org_id, sha256) 6. Commit OK 7. HTTP 201 Created (File JSON) Auth & Tenant Isolation Check Client GoRoute AI Gateway Local Disk (0600 mode) SHA-256 Digest PostgreSQL

Security & Integrity Controls​

  1. POSIX File System Isolation: The gateway daemon creates its storage root with directory permissions 0700 (drwx------) and all uploaded blobs with file permissions 0600 (-rw-------). Unprivileged local system processes cannot read or modify tenant files.
  2. Streaming Cryptographic Hashing: Rather than buffering up to 512 MB in memory to calculate hashes, GoRoute utilizes an io.MultiWriter(dst, hasher) that writes to disk while concurrently streaming bytes into a SHA-256 digest engine.
  3. Multi-Tenant Boundary & Quotas: Every database query filters by WHERE org_id = $1. Tenants cannot read, download, or delete files belonging to another organization. Before writing to disk, the gateway tracks both persisted organization byte totals and in-flight upload reservations so concurrent uploads cannot race past server.max_file_storage_bytes_per_org.
  4. Multipart Spill Cleanup: Temporary multipart spill files created during ParseMultipartForm are explicitly removed via defer r.MultipartForm.RemoveAll() on both success and error paths.

File Schemas​

File Object Schema (CanonicalFile)​

{
"id": "file-89fa21bc-1240-4fe9-b001-c8120fa23e11",
"object": "file",
"bytes": 284102,
"created_at": 1740000000,
"filename": "batch_prompts_2026.jsonl",
"purpose": "batch",
"status": "uploaded",
"content_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}

Code Examples​

# 1. Upload a JSONL file for Batch processing
curl -X POST http://localhost:8080/v1/files \
-H "Authorization: Bearer sk-gw-prod-7f9a2b8c4d1e" \
-F "file=@requests.jsonl" \
-F "purpose=batch"

# 2. List all files for the organization
curl -X GET http://localhost:8080/v1/files \
-H "Authorization: Bearer sk-gw-prod-7f9a2b8c4d1e"

# 3. Retrieve file metadata
curl -X GET http://localhost:8080/v1/files/file-89fa21bc-1240-4fe9-b001-c8120fa23e11 \
-H "Authorization: Bearer sk-gw-prod-7f9a2b8c4d1e"

# 4. Stream / Download file content
curl -X GET http://localhost:8080/v1/files/file-89fa21bc-1240-4fe9-b001-c8120fa23e11/content \
-H "Authorization: Bearer sk-gw-prod-7f9a2b8c4d1e" \
-o downloaded_requests.jsonl

# 5. Delete file
curl -X DELETE http://localhost:8080/v1/files/file-89fa21bc-1240-4fe9-b001-c8120fa23e11 \
-H "Authorization: Bearer sk-gw-prod-7f9a2b8c4d1e"