Skip to main content
POST
/
v1
/
files
Upload File
curl --request POST \
  --url https://api.gravixlayer.com/v1/files \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file' \
  --form purpose=assistants
Overview The Upload File API allows you to store files on Gravix Layer for use across various endpoints including vector storage, fine-tuning, and batch processing. Uploaded files are securely stored and can be referenced by their unique file ID. Supported File Types

Documents

.pdf, .txt, .md, .docx Perfect for document processing and RAG

Data Files

.json, .jsonl, .csv Structured data for training and batch processing

Images

.jpg, .jpeg, .png, .webp Visual content for vision models

Code Files

.py, .js, .ts, .html, .css Source code for analysis and generation
Key Features
  • Multi-format support for documents, images, and data files
  • Automatic expiration with configurable retention periods
  • Secure storage with encryption at rest
  • Purpose-based organization for different use cases
  • Size limits up to 200MB per file
Common Use Cases
Upload documents for semantic search and RAG:
# Upload document for vector processing
with open("knowledge_base.pdf", "rb") as file:
    response = client.files.create(
        file=file,
        purpose="user_data"
    )
Request Parameters
FieldTypeRequiredDescription
filefile (binary)YesThe file to upload. Maximum size: 200MB.
purposestringYesThe intended purpose of the file. Must be one of: batch, batch_output, fine-tune, vision, user_data, evals.
expires_afterinteger (seconds)NoExpiration time in seconds. If provided, the file will be automatically deleted after this duration.
Example Requests 
curl -X POST https://api.gravixlayer.com/v1/files \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -F "file=@/path/to/your/file.jsonl" \
  -F "purpose=fine-tune" \
  -F "expires_after=86400"
Response 
{
  "file_name": "Test_POST.pdf",
  "message": "file uploaded",
  "purpose": "fine-tune",
  "file_id": "file_abc123",
  "size_bytes": 1048576,
  "created_at": 1697123456
}
Error Responses
Status CodeError TypeDescription
400invalid_request_errorInvalid file format or missing required fields
413file_too_largeFile exceeds 200MB limit
429rate_limit_exceededToo many upload requests
500api_errorInternal server error
Best Practices
Always validate file size and format before uploading to prevent errors and optimize performance.
File Size Guidelines
  • Small files (< 1MB): Upload immediately
  • Medium files (1MB - 10MB): Consider compression for faster uploads
  • Large files (10MB - 200MB): Use chunked upload for reliability
  • Files > 200MB: Split into smaller parts or compress
Purpose Selection
  • user_data: General documents and content for RAG
  • fine-tune: Training datasets in JSONL format
  • batch: Multiple requests for batch processing
  • vision: Images for vision model processing
  • evals: Evaluation datasets and test files
Security Considerations Always validate and sanitize uploaded files: File Validation 
import os

def validate_file_upload(file_path, max_size_mb=200):
    """Validate file before upload"""
    if not os.path.exists(file_path):
        raise ValueError("File does not exist")
    
    file_size = os.path.getsize(file_path)
    max_size_bytes = max_size_mb * 1024 * 1024
    
    if file_size > max_size_bytes:
        raise ValueError(f"File size {file_size / 1024 / 1024:.1f}MB exceeds {max_size_mb}MB limit")
    
    if file_size == 0:
        raise ValueError("File is empty")
    
    return True

# Usage
validate_file_upload("/path/to/file.jsonl")

Authorizations

​
Authorization
string
header
required

API key authentication. Get your API key from the Gravix Layer Dashboard.

Body

multipart/form-data
​
file
file
required

The file to upload

​
purpose
enum<string>
required

The intended purpose of the file

Available options:
assistants,
vision,
batch,
fine-tune

Response

200

File uploaded successfully