Skip to main content
Uploads a file to S3 storage and returns the file ID and metadata. You can optionally specify a custom path within your organization’s storage bucket. 
POST https://api.worqhat.com/storage/upload

​
What Does This Endpoint Do?

This endpoint allows you to upload files to WorqHat’s secure S3 storage. Think of it like uploading a file to Google Drive or Dropbox - you send a file and get back a unique ID and download URL that you can use later.

​
When to Use Upload File

You’ll find this endpoint useful when you need to:
  • Store user documents: Upload PDFs, images, or other files from your users
  • Backup application data: Save important files to secure cloud storage
  • Share files: Upload files that need to be accessible via URLs
  • Store media assets: Upload images, videos, or audio files for your application
  • Archive data: Store files for long-term retention
  • Process files: Upload files for AI processing or analysis

​
How It Works

  1. You send a file (binary data) to the endpoint
  2. You can optionally specify a custom path to organize your files
  3. The API stores the file in S3 and returns metadata including a unique ID
  4. You can use the returned ID to fetch or delete the file later

​
Code Examples

​
Example 1: Basic File Upload

This example shows how to upload a file with an auto-generated path.
  • Node.js
  • Python
  • Go
  • cURL
import Worqhat from 'worqhat';

// Initialize the client with your API key
const client = new Worqhat({
  apiKey: process.env.WORQHAT_API_KEY, // Always use environment variables for API keys
});

async function uploadDocument() {
  try {
    // Create FormData for file upload
    const formData = new FormData();
    const fileInput = document.querySelector('input[type="file"]');
    formData.append('file', fileInput.files[0]);
    
    // Call the uploadFile method
    const response = await client.storage.uploadFile({
      file: fileInput.files[0],
      path: 'documents/' // Optional custom path
    });
    
    // Handle the successful response
    console.log('File uploaded successfully!');
    console.log('File ID:', response.file.id);
    console.log('Download URL:', response.file.url);
    console.log('File size:', response.file.size, 'bytes');
    return response;
  } catch (error) {
    // Handle any errors
    console.error('Error uploading file:', error.message);
  }
}

// Call the function
uploadDocument();

​
Example 2: Upload with Custom Path

This example shows how to upload a file to a specific organized path.
  • Node.js
  • Python
  • Go
  • cURL
import Worqhat from 'worqhat';

// Initialize the client with your API key
const client = new Worqhat({
  apiKey: process.env.WORQHAT_API_KEY,
});

async function uploadInvoice() {
  try {
    // Upload invoice to organized path
    const response = await client.storage.uploadFile({
      file: invoiceFile,
      path: 'invoices/2025/january/' // Organized path structure
    });
    
    // Handle the successful response
    console.log(`Invoice uploaded to: ${response.file.path}`);
    console.log('File ID:', response.file.id);
    return response;
  } catch (error) {
    console.error('Error uploading invoice:', error.message);
  }
}

uploadInvoice();

​
Request Body Explained

​
file
binary
required
The file to upload. This should be the actual file data (binary content). Maximum file size is 50MB.Supported file types include: PDF, images (JPG, PNG, GIF), documents (DOC, DOCX), spreadsheets (XLS, XLSX), and more.
​
path
string
Optional custom path within your organization’s storage. This helps organize your files into folders.Examples: "documents/", "invoices/2025/", "user-uploads/images/"If not provided, the file will be stored in the root of your organization’s storage.

​
Response Fields Explained

​
success
boolean
true if the upload was successful, false otherwise.
​
file
object
An object containing all the file metadata and information.
​
file.id
string
Unique identifier for the uploaded file. Use this ID to fetch or delete the file later.
​
file.filename
string
The original name of the uploaded file.
​
file.path
string
The full path where the file is stored in your organization’s storage.
​
file.size
integer
The size of the uploaded file in bytes.
​
file.contentType
string
The MIME type of the uploaded file (e.g., “application/pdf”, “image/jpeg”).
​
file.uploadedAt
string
The timestamp when the file was uploaded (ISO 8601 format).
​
file.url
string
Direct URL to access the uploaded file. This URL is publicly accessible.

​
Example Response

{
  "success": true,
  "file": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "filename": "invoice_2025.pdf",
    "path": "org_123/documents/invoices/invoice_2025.pdf",
    "size": 245678,
    "contentType": "application/pdf",
    "uploadedAt": "2025-07-26T03:28:08.123Z",
    "url": "https://storage.worqhat.com/org_123/documents/invoices/invoice_2025.pdf"
  }
}

​
Common Errors and How to Fix Them

ErrorCauseSolution
”File too large”File exceeds 50MB limitCompress the file or split it into smaller parts
”Invalid file type”File type is not supportedUse a supported file format
”Missing file”No file was provided in the requestInclude a file in your request
”Unauthorized”Invalid or missing API keyCheck that you’re using a valid API key
”Storage quota exceeded”Organization has reached storage limitContact support or upgrade your plan

​
Tips for Successful Uploads

  • Use organized paths to keep your files well-structured
  • Check file size before uploading (50MB limit)
  • Use appropriate file types for your use case
  • Save the file ID for future reference and operations
  • Consider file compression for large files
  • Use meaningful filenames to make files easier to identify
⌘I