TWIGZ Backend API Documentation

Overview

The Utilities API provides essential system functions including secure file upload URL generation and other utility operations needed across the platform. Location: convex/shared/utils.ts

Generate Upload URL

Generates a secure upload URL for file uploads to Convex storage.

const uploadUrl = await convex.mutation(api.shared.utils.generateUploadUrl);

// Use the URL to upload a file
const file = new File(['content'], 'example.jpg', { type: 'image/jpeg' });

const response = await fetch(uploadUrl, {
  method: 'POST',
  body: file
});

const { storageId } = await response.json();
console.log('File uploaded with ID:', storageId);

const uploadUrl = await convex.mutation("shared.utils.generateUploadUrl");

// Upload file using the URL
const fileInput = document.getElementById('fileInput');
const file = fileInput.files[0];

const response = await fetch(uploadUrl, {
  method: 'POST',
  body: file
});

const { storageId } = await response.json();

import requests

# Get upload URL
response = requests.post(
    f"{CONVEX_URL}/api/mutation",
    json={
        "path": "shared.utils.generateUploadUrl",
        "args": {}
    },
    headers={"Authorization": f"Bearer {token}"}
)

upload_url = response.json()

# Upload file
with open('image.jpg', 'rb') as f:
    upload_response = requests.post(upload_url, files={'file': f})
    storage_id = upload_response.json()['storageId']

# Get upload URL
curl -X POST "https://your-deployment.convex.cloud/api/mutation" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "path": "shared.utils.generateUploadUrl",
    "args": {}
  }'

# Upload file (use the returned URL)
curl -X POST "UPLOAD_URL_FROM_RESPONSE" \
  -F "file=@image.jpg"

"https://upload.convex.dev/upload/abc123def456?token=xyz789"

File Upload Process

The file upload process follows these steps:

Generate Upload URL

Call generateUploadUrl to get a secure, temporary upload URL

Upload File

Use the returned URL to upload your file via HTTP POST

Get Storage ID

The upload response contains a storageId that you can use to reference the file

Use Storage ID

Use the storageId in other API calls (e.g., creating products with images)

Supported File Types

Images

Formats: JPEG, PNG, WebP, GIF, SVG
Max Size: 10MB
Recommended: WebP for web, PNG for transparency

Documents

Formats: PDF, DOC, DOCX, TXT
Max Size: 25MB
Use Case: Trade licenses, contracts, receipts

Videos

Formats: MP4, WebM, MOV
Max Size: 100MB
Use Case: Product demos, store tours

Audio

Formats: MP3, WAV, OGG
Max Size: 25MB
Use Case: Voice notes, audio descriptions

Complete Upload Example

Here’s a complete example showing how to upload a file and use it:

import { useState } from 'react';
import { useMutation } from 'convex/react';
import { api } from './convex/_generated/api';

function FileUploadComponent() {
  const [uploading, setUploading] = useState(false);
  const [storageId, setStorageId] = useState<string | null>(null);
  
  const generateUploadUrl = useMutation(api.shared.utils.generateUploadUrl);
  const createProduct = useMutation(api.shared.products.createProduct);

  const handleFileUpload = async (file: File) => {
    try {
      setUploading(true);
      
      // Step 1: Generate upload URL
      const uploadUrl = await generateUploadUrl();
      
      // Step 2: Upload file
      const response = await fetch(uploadUrl, {
        method: 'POST',
        body: file
      });
      
      const { storageId } = await response.json();
      setStorageId(storageId);
      
      // Step 3: Use storage ID in product creation
      await createProduct({
        name: "New Product",
        category: "k123456789",
        price: 19.99,
        isActive: true,
        primaryImage: storageId // Use the uploaded file
      });
      
      console.log('Product created with uploaded image!');
      
    } catch (error) {
      console.error('Upload failed:', error);
    } finally {
      setUploading(false);
    }
  };

  return (
    <div>
      <input
        type="file"
        accept="image/*"
        onChange={(e) => {
          const file = e.target.files?.[0];
          if (file) handleFileUpload(file);
        }}
        disabled={uploading}
      />
      {uploading && <p>Uploading...</p>}
      {storageId && <p>Upload successful! ID: {storageId}</p>}
    </div>
  );
}

async function uploadFile(fileInput) {
  const file = fileInput.files[0];
  if (!file) return;

  try {
    // Step 1: Generate upload URL
    const uploadUrlResponse = await fetch('/api/generate-upload-url', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`
      }
    });
    const { uploadUrl } = await uploadUrlResponse.json();

    // Step 2: Upload file
    const formData = new FormData();
    formData.append('file', file);

    const uploadResponse = await fetch(uploadUrl, {
      method: 'POST',
      body: file
    });

    const { storageId } = await uploadResponse.json();
    console.log('File uploaded successfully:', storageId);

    return storageId;

  } catch (error) {
    console.error('Upload failed:', error);
    throw error;
  }
}

// Usage
document.getElementById('fileInput').addEventListener('change', async (e) => {
  const storageId = await uploadFile(e.target);
  // Use storageId in your application
});

Security & Best Practices

File Validation

Always validate file types and sizes on the client side before uploading:

function validateFile(file: File): boolean {
  // Check file size (10MB limit for images)
  if (file.size > 10 * 1024 * 1024) {
    throw new Error('File too large. Maximum size is 10MB.');
  }
  
  // Check file type
  const allowedTypes = ['image/jpeg', 'image/png', 'image/webp'];
  if (!allowedTypes.includes(file.type)) {
    throw new Error('Invalid file type. Only JPEG, PNG, and WebP are allowed.');
  }
  
  return true;
}

Upload URL Expiration

Upload URLs expire after 1 hour for security. Generate a new URL if upload fails:

async function uploadWithRetry(file: File, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const uploadUrl = await generateUploadUrl();
      const response = await fetch(uploadUrl, {
        method: 'POST',
        body: file
      });
      
      if (response.ok) {
        return await response.json();
      }
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      console.warn(`Upload attempt ${i + 1} failed, retrying...`);
    }
  }
}

Progress Tracking

Track upload progress for better user experience:

async function uploadWithProgress(file: File, onProgress: (progress: number) => void) {
  const uploadUrl = await generateUploadUrl();
  
  return new Promise((resolve, reject) => {
    const xhr = new XMLHttpRequest();
    
    xhr.upload.addEventListener('progress', (e) => {
      if (e.lengthComputable) {
        const progress = (e.loaded / e.total) * 100;
        onProgress(progress);
      }
    });
    
    xhr.addEventListener('load', () => {
      if (xhr.status === 200) {
        resolve(JSON.parse(xhr.responseText));
      } else {
        reject(new Error('Upload failed'));
      }
    });
    
    xhr.addEventListener('error', () => reject(new Error('Upload failed')));
    
    xhr.open('POST', uploadUrl);
    xhr.send(file);
  });
}

Error Handling

Upload URL generation failed

Status Code: 500

{
  "error": "Failed to generate upload URL. Please try again."
}

File upload failed

Status Code: 400

{
  "error": "File upload failed",
  "details": "File size exceeds maximum limit"
}

Invalid file type

Status Code: 400

{
  "error": "Invalid file type",
  "allowedTypes": ["image/jpeg", "image/png", "image/webp"]
}

Upload URLs are temporary and expire after 1 hour. Always generate a fresh URL for each upload operation.

For better performance, compress images before uploading and use WebP format when possible for web applications.

Shared Functions

Store Management

Customer Experience

Admin & Platform

HTTP Endpoints

Scheduled Tasks

Database

Development

Utilities

Overview

Generate Upload URL

File Upload Process

Supported File Types

Images

Documents

Videos

Audio

Complete Upload Example

Security & Best Practices

Error Handling

​Overview

​Generate Upload URL

​File Upload Process

​Supported File Types

Images

Documents

Videos

Audio

​Complete Upload Example

​Security & Best Practices

​Error Handling

Overview

Generate Upload URL

File Upload Process

Supported File Types

Complete Upload Example

Security & Best Practices

Error Handling